A user account is required in order to edit this wiki, but we've had to disable public user registrations due to spam.

To request an account, ask an autoconfirmed user on Chat (such as one of these permanent autoconfirmed members).

Validator.nu Web Service Interface: Difference between revisions

From WHATWG Wiki
Jump to navigation Jump to search
(Add out= parameters)
No edit summary
 
(38 intermediate revisions by 3 users not shown)
Line 1: Line 1:
This is a inline-commentable updated wiki copy of [http://hsivonen.iki.fi/validator-ws-ideas/ the original article].
{{Obsolete|spec=https://github.com/validator/validator/wiki/Service-»-HTTP-interface}}
Validator.nu can be called as a Web service. Input and output modes can be chosen completely orthogonally. Responses and requests can be optionally compressed (independently of each other).


==Motivation==
(Please use the Web service API reasonably. See the [https://about.validator.nu/#tos Terms of Service].)


First, I assume there is some level of interest in doing RELAX NG
==Input Modes==
/ Schematron validation and HTML5 conformance checking. Next, it
 
would be nice to enable applications that deal with documents to make
For most Web service use cases, you should probably POST the document as the HTTP entity body.
these checks automatically in addition to having the functionality
 
available for human operators as a Web app. For example, [http://golem.ph.utexas.edu/~distler/blog/archives/001054.html a content management system might check the input it is given].
===Implemented===
 
* Document [[Validator.nu GET Input|URL as a GET parameter]]; the service retrieves the document by URL over HTTP or HTTPS.
* Document [[Validator.nu POST Body Input|POSTed as the HTTP entity body]]; parameters in query string as with GET.
* Document [[Validator.nu Textarea Input|POSTed as a <code>textarea</code> value]].
* Document [[Validator.nu Form Upload Input|POSTed as a form-based file upload]].
 
===Not Implemented===
 
* Document in a <CODE>data:</CODE> URI as a GET parameter.
* <code>application/x-www-form-urlencoded</code>
 
==Output Modes==
 
When using Validator.nu as a Web service back end, the [[Validator.nu XML Output|XML]] and [[Validator.nu JSON Output|JSON]] output formats are recommended for forward compatibility. The available JSON tooling probably makes consuming JSON easier. The XML format contains XHTML elaborations that are not available in JSON. Both formats are streaming, but streaming XML parsers are more readily available. XML cannot represent some input strings faithfully.
 
===Implemented===
 
* HTML with microformat-style <CODE>class</CODE> annotations (default output; should not be assumed to be forward-compatibly stable).
* XHTML with microformat-style <CODE>class</CODE> annotations (append <code>&out=xhtml</code> to URL; should not be assumed to be forward-compatibly stable).
* [[Validator.nu XML Output|XML]] (append <code>&out=xml</code> to URL).
* [[Validator.nu JSON Output|JSON]] (append <code>&out=json</code> to URL).
* [[Validator.nu GNU Output|GNU error format]] (append <code>&out=gnu</code> to URL).
* Human-readably plain text (append <code>&out=text</code> to URL; should not be assumed to be forward-compatibly stable for machine parsing—use the GNU format for that).
 
===Not Implemented===
 
* Relaxed-compatible (lacks a spec)
* Unicorn-compatible (hoping that Unicorn changes instead)
* W3C Validator-compatible SOAP (legacy)
* EARL (not implemented; domain modeling mismatch)


Java apps could just integrate a private copy of the Free Software
==Compression==
back end of the [http://hsivonen.iki.fi/validator/ validation]
/ [http://hsivonen.iki.fi/validator/html5/ conformance checking] service. However, non-Java apps would benefit from
having the validation / conformance checking service running out of
process and having an interface for talking to the out-of-process
Java service. The service instance could be hosted publicly or as a
local copy. Even some Java developers would elect to use such a
service instead of integrating the back end as part of their own app.


==Input Modes==
Validator.nu supports compression in order to save bandwidth.
 
===Request Compression===
 
Validator.nu supports HTTP request compression. To use it, compress the request entity body using gzip and specify <code>Content-Encoding: gzip</code> as a ''request'' header.
 
===Response Compression===


The schemas are expected to be relatively static. Therefore, I
Validator.nu supports HTTP response compression. Please use it. Response compression is orthogonal to the input methods and output formats.
think preloading them into the service or letting the service
retrieve them is sufficient. Identification by URI works in both
cases.


What needs different input modes is the document that is checked.
The standard HTTP gzip mechanism is used. To indicated that you prepared to handle gzipped responses, include the <code>Accept-Encoding: gzip</code> request header. When the header is present, Validator.nu will gzip compress the response. You should also be prepared to receive an uncompressed, though, since in the future it may make sense to turn off compression under heavy CPU load.


I think the following modes would make sense:
==Sample Code==


* Document URI as a GET parameter; the service retrieves the
There a [https://about.validator.nu/html5check.py sample Python program] that shows how to deal with compression and redirects. (It may not be exemplary Python, though.)
document by URI (already implemented).
* Document in a <CODE>data:</CODE> URI as a GET parameter.
* Document POSTed as the HTTP entity body (the preferred Web
service mode; already implemented).
* Document POSTed as an <CODE>application/x-www-form-urlencoded</CODE>
form field value.
* Document POSTed as a <CODE>multipart/form-data</CODE> file
upload.


In the first three modes, additional parameters would be
==CORS Example==
communicated in the URI query string. In the last two modes,
additional parameters would be communicated like corresponding from
fields are communicated as <CODE>application/x-www-form-urlencoded</CODE>
and <CODE>multipart/form-data</CODE>.


I don’t particularly like the last two modes, but they are
You can also hit the API using [https://developer.mozilla.org/en-US/docs/HTTP_access_control CORS] over AJAX. [https://gist.github.com/gists/3902535 Basic example using jQuery].
needed to address feature requests and for parity with other
services. Also, unlike the first three modes, the last two modes need
companion UI changes, which is not nice. As a further complication,
the last two don’t come naturally with a <CODE>Content-Type</CODE>
for dispatching to an HTML5 parser or to an XML parser.


All these input modes would share the same “service endpoint
==Sample Messages==
URI” (and the same servlet class). The different cases can be
distinguished from the HTTP method and in the POST cases from the
<CODE>Content-Type</CODE> request header.


==Output Modes==
There are [http://hsivonen.com/test/moz/messages-types/ documents for provoking different message types].


A Web service probably calls for an XML output format for maximal
{|
tool chain integration even though the current HTML output format
|-
makes sense for browsers and can carry all the necessary data.
! No message
| [https://html5.validator.nu/?doc=http%3A%2F%2Fhsivonen.com%2Ftest%2Fmoz%2Fmessages-types%2Fno-message.html HTML]
| [https://html5.validator.nu/?doc=http%3A%2F%2Fhsivonen.com%2Ftest%2Fmoz%2Fmessages-types%2Fno-message.html&out=xhtml XHTML]
| [https://html5.validator.nu/?doc=http%3A%2F%2Fhsivonen.com%2Ftest%2Fmoz%2Fmessages-types%2Fno-message.html&out=xml XML]
| [https://html5.validator.nu/?doc=http%3A%2F%2Fhsivonen.com%2Ftest%2Fmoz%2Fmessages-types%2Fno-message.html&out=json JSON]
| [https://html5.validator.nu/?doc=http%3A%2F%2Fhsivonen.com%2Ftest%2Fmoz%2Fmessages-types%2Fno-message.html&out=gnu GNU]
| [https://html5.validator.nu/?doc=http%3A%2F%2Fhsivonen.com%2Ftest%2Fmoz%2Fmessages-types%2Fno-message.html&out=text Text]
|-
! Info
| [https://validator.nu/?doc=http%3A%2F%2Fhsivonen.com%2Ftest%2Fmoz%2Fmessages-types%2Finfo.svg HTML]
| [https://validator.nu/?doc=http%3A%2F%2Fhsivonen.com%2Ftest%2Fmoz%2Fmessages-types%2Finfo.svg&out=xhtml XHTML]
| [https://validator.nu/?doc=http%3A%2F%2Fhsivonen.com%2Ftest%2Fmoz%2Fmessages-types%2Finfo.svg&out=xml XML]
| [https://validator.nu/?doc=http%3A%2F%2Fhsivonen.com%2Ftest%2Fmoz%2Fmessages-types%2Finfo.svg&out=json JSON]
| [https://validator.nu/?doc=http%3A%2F%2Fhsivonen.com%2Ftest%2Fmoz%2Fmessages-types%2Finfo.svg&out=gnu GNU]
| [https://validator.nu/?doc=http%3A%2F%2Fhsivonen.com%2Ftest%2Fmoz%2Fmessages-types%2Finfo.svg&out=text Text]
|-
! Warning
| [https://html5.validator.nu/?doc=http%3A%2F%2Fhsivonen.com%2Ftest%2Fmoz%2Fmessages-types%2Fwarning.html HTML]
| [https://html5.validator.nu/?doc=http%3A%2F%2Fhsivonen.com%2Ftest%2Fmoz%2Fmessages-types%2Fwarning.html&out=xhtml XHTML]
| [https://html5.validator.nu/?doc=http%3A%2F%2Fhsivonen.com%2Ftest%2Fmoz%2Fmessages-types%2Fwarning.html&out=xml XML]
| [https://html5.validator.nu/?doc=http%3A%2F%2Fhsivonen.com%2Ftest%2Fmoz%2Fmessages-types%2Fwarning.html&out=json JSON]
| [https://html5.validator.nu/?doc=http%3A%2F%2Fhsivonen.com%2Ftest%2Fmoz%2Fmessages-types%2Fwarning.html&out=gnu GNU]
| [https://html5.validator.nu/?doc=http%3A%2F%2Fhsivonen.com%2Ftest%2Fmoz%2Fmessages-types%2Fwarning.html&out=text Text]
|-
! Error (precise location)
| [https://html5.validator.nu/?doc=http%3A%2F%2Fhsivonen.com%2Ftest%2Fmoz%2Fmessages-types%2Fprecise-error.html HTML]
| [https://html5.validator.nu/?doc=http%3A%2F%2Fhsivonen.com%2Ftest%2Fmoz%2Fmessages-types%2Fprecise-error.html&out=xhtml XHTML]
| [https://html5.validator.nu/?doc=http%3A%2F%2Fhsivonen.com%2Ftest%2Fmoz%2Fmessages-types%2Fprecise-error.html&out=xml XML]
| [https://html5.validator.nu/?doc=http%3A%2F%2Fhsivonen.com%2Ftest%2Fmoz%2Fmessages-types%2Fprecise-error.html&out=json JSON]
| [https://html5.validator.nu/?doc=http%3A%2F%2Fhsivonen.com%2Ftest%2Fmoz%2Fmessages-types%2Fprecise-error.html&out=gnu GNU]
| [https://html5.validator.nu/?doc=http%3A%2F%2Fhsivonen.com%2Ftest%2Fmoz%2Fmessages-types%2Fprecise-error.html&out=text Text]
|-
! Error (range location)
| [https://html5.validator.nu/?doc=http%3A%2F%2Fhsivonen.com%2Ftest%2Fmoz%2Fmessages-types%2Frange-error.html HTML]
| [https://html5.validator.nu/?doc=http%3A%2F%2Fhsivonen.com%2Ftest%2Fmoz%2Fmessages-types%2Frange-error.html&out=xhtml XHTML]
| [https://html5.validator.nu/?doc=http%3A%2F%2Fhsivonen.com%2Ftest%2Fmoz%2Fmessages-types%2Frange-error.html&out=xml XML]
| [https://html5.validator.nu/?doc=http%3A%2F%2Fhsivonen.com%2Ftest%2Fmoz%2Fmessages-types%2Frange-error.html&out=json JSON]
| [https://html5.validator.nu/?doc=http%3A%2F%2Fhsivonen.com%2Ftest%2Fmoz%2Fmessages-types%2Frange-error.html&out=gnu GNU]
| [https://html5.validator.nu/?doc=http%3A%2F%2Fhsivonen.com%2Ftest%2Fmoz%2Fmessages-types%2Frange-error.html&out=text Text]
|-
! Fatal
| [https://html5.validator.nu/?doc=http%3A%2F%2Fhsivonen.com%2Ftest%2Fmoz%2Fmessages-types%2Ffatal.xhtml HTML]
| [https://html5.validator.nu/?doc=http%3A%2F%2Fhsivonen.com%2Ftest%2Fmoz%2Fmessages-types%2Ffatal.xhtml&out=xhtml XHTML]
| [https://html5.validator.nu/?doc=http%3A%2F%2Fhsivonen.com%2Ftest%2Fmoz%2Fmessages-types%2Ffatal.xhtml&out=xml XML]
| [https://html5.validator.nu/?doc=http%3A%2F%2Fhsivonen.com%2Ftest%2Fmoz%2Fmessages-types%2Ffatal.xhtml&out=json JSON]
| [https://html5.validator.nu/?doc=http%3A%2F%2Fhsivonen.com%2Ftest%2Fmoz%2Fmessages-types%2Ffatal.xhtml&out=gnu GNU]
| [https://html5.validator.nu/?doc=http%3A%2F%2Fhsivonen.com%2Ftest%2Fmoz%2Fmessages-types%2Ffatal.xhtml&out=text Text]
|-
! IO
| [https://html5.validator.nu/?doc=http%3A%2F%2Fhsivonen.com%2Ftest%2Fmoz%2Fmessages-types%2F404.html HTML]
| [https://html5.validator.nu/?doc=http%3A%2F%2Fhsivonen.com%2Ftest%2Fmoz%2Fmessages-types%2F404.html&out=xhtml XHTML]
| [https://html5.validator.nu/?doc=http%3A%2F%2Fhsivonen.com%2Ftest%2Fmoz%2Fmessages-types%2F404.html&out=xml XML]
| [https://html5.validator.nu/?doc=http%3A%2F%2Fhsivonen.com%2Ftest%2Fmoz%2Fmessages-types%2F404.html&out=json JSON]
| [https://html5.validator.nu/?doc=http%3A%2F%2Fhsivonen.com%2Ftest%2Fmoz%2Fmessages-types%2F404.html&out=gnu GNU]
| [https://html5.validator.nu/?doc=http%3A%2F%2Fhsivonen.com%2Ftest%2Fmoz%2Fmessages-types%2F404.html&out=text Text]
|}


I think the following modes could make sense:


* HTML with microformat-style <CODE>class</CODE> annotations
(already implemented; default output).
* XHTML with microformat-style <CODE>class</CODE> annotations (already implemented; append <code>&out=xhtml</code> to URL).
* [[Validator.nu XML Output|XML format designed specifically for Validator.nu.]] (already implemented; append <code>&out=xml</code> to URL).
* [[Validator.nu JSON Output|JSON]] (already implemented; append <code>&out=json</code> to URL).
* Human-readably plain text (already implemented; append <code>&out=text</code> to URL).
* [[Validator.nu GNU Output|GNU error format]] (not implemented; needs a better spec)
* Relaxed-compatible (not implemented; lacks a spec)
* Unicorn-compatible (not implemented)
* W3C Validator-compatible SOAP (not implemented; legacy)
* EARL (not implemented; domain modeling mismatch)


For the HTML and XHTML output formats, there could be an option
[[Category:Validator.nu Documentation]]
for suppressing the input form. The output default should be HTML for
the browser-targeted input formats. However, the custom XML format
might be a reasonable default when the input document was POSTed as
the entity body.

Latest revision as of 04:36, 29 December 2016

This document is obsolete.

For the current specification, see: https://github.com/validator/validator/wiki/Service-»-HTTP-interface

Validator.nu can be called as a Web service. Input and output modes can be chosen completely orthogonally. Responses and requests can be optionally compressed (independently of each other).

(Please use the Web service API reasonably. See the Terms of Service.)

Input Modes

For most Web service use cases, you should probably POST the document as the HTTP entity body.

Implemented

Not Implemented

  • Document in a data: URI as a GET parameter.
  • application/x-www-form-urlencoded

Output Modes

When using Validator.nu as a Web service back end, the XML and JSON output formats are recommended for forward compatibility. The available JSON tooling probably makes consuming JSON easier. The XML format contains XHTML elaborations that are not available in JSON. Both formats are streaming, but streaming XML parsers are more readily available. XML cannot represent some input strings faithfully.

Implemented

  • HTML with microformat-style class annotations (default output; should not be assumed to be forward-compatibly stable).
  • XHTML with microformat-style class annotations (append &out=xhtml to URL; should not be assumed to be forward-compatibly stable).
  • XML (append &out=xml to URL).
  • JSON (append &out=json to URL).
  • GNU error format (append &out=gnu to URL).
  • Human-readably plain text (append &out=text to URL; should not be assumed to be forward-compatibly stable for machine parsing—use the GNU format for that).

Not Implemented

  • Relaxed-compatible (lacks a spec)
  • Unicorn-compatible (hoping that Unicorn changes instead)
  • W3C Validator-compatible SOAP (legacy)
  • EARL (not implemented; domain modeling mismatch)

Compression

Validator.nu supports compression in order to save bandwidth.

Request Compression

Validator.nu supports HTTP request compression. To use it, compress the request entity body using gzip and specify Content-Encoding: gzip as a request header.

Response Compression

Validator.nu supports HTTP response compression. Please use it. Response compression is orthogonal to the input methods and output formats.

The standard HTTP gzip mechanism is used. To indicated that you prepared to handle gzipped responses, include the Accept-Encoding: gzip request header. When the header is present, Validator.nu will gzip compress the response. You should also be prepared to receive an uncompressed, though, since in the future it may make sense to turn off compression under heavy CPU load.

Sample Code

There a sample Python program that shows how to deal with compression and redirects. (It may not be exemplary Python, though.)

CORS Example

You can also hit the API using CORS over AJAX. Basic example using jQuery.

Sample Messages

There are documents for provoking different message types.

No message HTML XHTML XML JSON GNU Text
Info HTML XHTML XML JSON GNU Text
Warning HTML XHTML XML JSON GNU Text
Error (precise location) HTML XHTML XML JSON GNU Text
Error (range location) HTML XHTML XML JSON GNU Text
Fatal HTML XHTML XML JSON GNU Text
IO HTML XHTML XML JSON GNU Text