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
(→‎Input Modes: Categorize)
Line 3: Line 3:
==Input Modes==
==Input Modes==


The schemas are expected to be relatively static. Therefore, I
For most Web service use cases, you should probably POST the document as the HTTP entity body.
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.
===Implemented===


I think the following modes would make sense:
* Document URI as a GET parameter; the service retrieves the document by URI over HTTP or HTTPS.
* Document POSTed as the HTTP entity body; parameters in query string as with GET.
* 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.
 
===Not Implemented===


* Document URI as a GET parameter; the service retrieves the
document by URI (already implemented).
* Document in a <CODE>data:</CODE> URI as a GET parameter.
* 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
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
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
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==
==Output Modes==

Revision as of 20:33, 26 November 2007

Validator.nu can be called as a Web service. This page documents how.

Input Modes

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

Implemented

  • Document URI as a GET parameter; the service retrieves the document by URI over HTTP or HTTPS.
  • Document POSTed as the HTTP entity body; parameters in query string as with GET.
  • Document POSTed as an application/x-www-form-urlencoded form field value.
  • Document POSTed as a multipart/form-data file upload.

Not Implemented

  • Document in a data: URI as a GET parameter.

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).
  • Human-readably plain text (append &out=text to URL; should not be assumed to be forward-compatibly stable for machine parsing).

Not Implemented

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