SubSift REST API: Return Formats

Supported Formats

The SubSift REST API can return data in the following representational formats:

csv CSV (Comma-Separated Values) is a simple text format for a database table. CSV is not ideal for hierachical data but is useful for flat structures like matrices. See http://en.wikipedia.org/wiki/Comma-separated_values
json JSON (JavaScript Object Notation) is a lightweight data-interchange format that is a subset of the object literal notation of JavaScript. See http://www.json.org
rdf RDF (Resource Description Framework) is graph-based format for describing and connecting URIs. RDF is defined by a family World Wide Web Consortium (W3C) specifications. See http://en.wikipedia.org/wiki/Resource_Description_Framework
terms Terms are the data format of the Prolog logic programming language. SubSift produces ground terms suitable for consulting or asserting into a Prolog database. See http://en.wikipedia.org/wiki/Prolog and SWI-Prolog.
xml XML (Extensible Markup Language) is a set of rules for encoding documents electronically in a format defined by the World Wide Web Consortium (W3C). See http://www.w3.org/XML
yaml YAML (YAML Ain't Markup Language) is a human friendly data serialization standard for a wide range of programming languages. See http://www.yaml.org

Default Format

If no specific format is specified then the returned representational format defaults to xml.

For example, the following url returns a result in xml format.

http://subsift.ilrt.bris.ac.uk/kdd09/bookmarks/pc

NOTE: At the next release, SubSift's default format may be changing from XML to JSON. The dominant use cases are turning out to be browser-based client-side AJAX applications where JSON is a more sensible default than XML.

Specifying a Format

Method 1: Specifying a format by file extension

All SubSift REST API methods accept an optional :format parameter which specifies the representational format of the result. The :format parameter is normally supplied as a suffix to the method url, in the familiar style of file extensions, after the dot. For example, the following urls returns results in xml and json format respectively.

http://subsift.ilrt.bris.ac.uk/kdd09/bookmarks/pc.xml
http://subsift.ilrt.bris.ac.uk/kdd09/bookmarks/pc.json

The :format parameter may also be supplied as a separate http query parameter. This can be useful when selecting the format in a web form or setting it dynamically from a program. For example, the following url returns a result in json format.

http://subsift.ilrt.bris.ac.uk/kdd09/bookmarks/pc?format=json

Method 2: Specifying a format by content negotiation

As an alternative to specifying a format using file extensions, SubSift supports simple content negotiation. For example, although the following two HTTP GET requests share the same url, the first returns json and the second returns rdf.

curl -H "Accept: application/json" http://subsift.ilrt.bris.ac.uk/kdd09/bookmarks/pc
curl -H "Accept: application/rdf" http://subsift.ilrt.bris.ac.uk/kdd09/bookmarks/pc

Content negotiation relies on the HTTP Accept header parameter having a mime type value from the following table. Only single exact matches of these mime types are supported; lists of acceptable mime types, although legal under HTTP, are not supported by SubSift.

Mime Type Format
text/csv csv
application/json json
application/rdf rdf
application/prolog terms
application/xml xml
application/yaml yaml

Pretty Printing

All output formats have an optional parameter pretty which specifies whether pretty printing should be used to make the output more readable for humans - typically by splitting the output over multiple lines and using indentation. Values can be either 1 for true or 0 for false. The default is 1.

The following examples use pretty printing.

http://subsift.ilrt.bris.ac.uk/kdd09/bookmarks/pc.xml
http://subsift.ilrt.bris.ac.uk/kdd09/bookmarks/pc.xml?pretty=1
http://subsift.ilrt.bris.ac.uk/kdd09/bookmarks/pc.json
http://subsift.ilrt.bris.ac.uk/kdd09/bookmarks/pc.json?pretty=1

The following examples do not use pretty printing.

http://subsift.ilrt.bris.ac.uk/kdd09/bookmarks/pc.xml?pretty=0
http://subsift.ilrt.bris.ac.uk/kdd09/bookmarks/pc.json?pretty=0

In the SubSift REST API documentation, all examples are shown with pretty printing printing on.

Note that if the specified format is YAML then the value of pretty is ignored. This is because YAML is, by design, human-readable and has strict semantics associated with its layout and indentation.