Output Types

From n² wiki

This page describes how the Talis Platform API supports multiple output formats, i.e. content negotiation for its services.

Each service is defined to have 1 or more named output types which can be selected by specifying the appropriate media type in the client's accept header. Additionally, services with more than one output type will also support a query parameter called output. The value of this parameter is the lowercase name of the desired output type (see table, below).

Clients that specify the output parameter will always receive that output type regardless of the Accept headers they send.

In the documentation for each service the list of output types is always given in preferred order.

[edit] Determining the Output Format

Services determines the output type to be used in a response in the following order:

1. output parameter matches one of the service's output types
2. output parameter is supplied but does not match one of the service's output types - a 400 Bad Request response is given
3. Media type in the Accept header matches one of the service's output types, tested in preferred order
4. */* in the Accept header - the first output type in the output type list is used
5. No Accept header - the first output type in the output type list is used
6. No other matches - a 406 Not Acceptable response is given

[edit] Standard Named Output Types

The following table summarizes the named output types supported in the Platform. Consult the API Documentation for the relevant services to check whether a specific output type is supported.

Name	Description	Response Content Type	Accept Header	Output Parameter
HTML	The HTML response consists of an XHTML document and can be obtained either by specifying mime types of text/html or application/xhtml+xml in the request's accept header or by supplying an "output" query parameter with a value of "html". The response is sent with a content type header equal to the one matched in the accept header or text/html if the output parameter was specified.	text/html or application/xhtml+xml (see description)	text/html or application/xhtml+xml	html or xhtml
RDF	The response consists of an RDF/XML document	application/rdf+xml	application/rdf+xml	rdf
XML	The response consists of an XML document	application/xml	application/xml	xml
RSS	The response consists of an RSS 1.0 document	application/rss+xml	application/rss+xml	rss1
JSON	The response consists of a JavaScript Object Notation (JSON) document	application/json	application/json	json
Turtle	Terse Triple Language	text/turtle	text/turtle	turtle
N-Triples	N-Triples	text/plain	text/plain	ntriples

Note: for backwards compatibility, where the text/turtle media type is listed, the deprecated application/x-turtle media type is also supported, though it is given a lower weighting during Content Negotiation