-
Notifications
You must be signed in to change notification settings - Fork 265
Service » HTTP interface
The checker exposes an HTTP interface that allows it to 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.)
For most Web-service use cases, you probably want to POST the document as the HTTP entity body of the request.
- URL as a GET parameter; service retrieves document by URL over HTTP or HTTPS.
- POSTed as the HTTP entity body; parameters in query string as with GET.
- POSTed as a textarea value; parameters specified as form fields.
- POSTed as a form-based file upload; parameters specified as form fields.
- Document in a
data:
URI as a GET parameter. application/x-www-form-urlencoded
When using the checker 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.
- 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-readable 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).
The checker supports compression in order to save bandwidth.
The checker supports HTTP request compression. To use it, compress the
request entity body using gzip and specify Content-Encoding: gzip
as a
request header.
The checker 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, the checker 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.
There a sample Python program that shows how to deal with compression and redirects. (It may not be exemplary Python, though.)
You can also hit the API using CORS over AJAX. Basic example using jQuery:
// easy way to get current pages HTML
$.get('#', function(html) {
// emulate form post
var formData = new FormData();
formData.append('out', 'json');
formData.append('content', html);
// make ajax call
$.ajax({
url: "http://html5.validator.nu/",
data: formData,
dataType: "json",
type: "POST",
processData: false,
contentType: false,
success: function(data) {
console.log(data.messages); // data.messages is an array
},
error: function() {
console.warn(arguments);
}
});
});
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 |