Lawi API Formats

The Lawi Project API understands several different Formats, each useful in a variety of different programming contexts.

• Primary Formats

◦ XML: Easily parsed on many platforms in many languages.

◦ JSON: Can also be parsed in many languages, more lightweight, can easily be evaluated in Javascript.

• Secondary Formats

◦ Javascript: Same structure as JSON, use it for cross-domain requests in a browser (JSONP)

◦ RSS: All Collections of Tagcrumbs can be subscribed as a GeoRSS feed.

◦ KML: All Collections of Tagcrumbs can be viewed in Google Earth or any other KML compatible tool.

◦ RDF: Individual Placemarks can be requested as RDF.

For a generic application you should select one of the Primary Formats and stick with it for all calls to the Lawi Project API. Mixing the Formats in one application is possible, but not recommended. Select the Format with which you have the most experience or for which you can find the better tools for your programming language.

The Secondary Formats can prove very useful for smaller applications where you don’t need the full power of the Tagcrumbs API (e.g. widgets).

After you read about how to specify the Formats you can find out more details about each individual Format by clicking on the links above or in the sidebar.

The Primary Formats are available for all Endpoints of the Tagcrumbs API, while the Secondary Formats are only available on some Endpoints. Only the Primary Formats can be used to create and modify Resources.

Specifying the Format

It is possible to specify the Format in several different ways:

• Append the format to the URI

• Set HTTP Headers

Append the format to the URI

This is especially useful for tools where it is not possible or easy to set your own HTTP Headers.

To quickly view different Formats within your browser you can just surf on the Tagcrumbs website and append the Format manually to the current URL in the location bar of your browser.

URI

Format

http://www.tagcrumbs.com/sascha/tagcrumbs Current URI
http://www.tagcrumbs.com/sascha/tagcrumbs.xml XML
http://www.tagcrumbs.com/sascha/tagcrumbs.json JSON
http://www.tagcrumbs.com/sascha/tagcrumbs.js?callback=test Javascript
http://www.tagcrumbs.com/sascha/tagcrumbs.rss RSS
http://www.tagcrumbs.com/sascha/tagcrumbs.kml KML

Please notice that changing the extension just displays another Representation of the Resource. If you “delete” one Representation of the Resource all Representations will be deleted.

The format extensions can only be used to read data. If you want to modify Resources you have to set HTTP Headers as well, otherwise our Request Forgery Protection kicks in and will block your query, resulting in a returned HTML page with an HTTP Status Code of 400 (Bad Request).

Set HTTP Headers

The HTTP protocol uses HTTP Headers to specify which media type is used in a request and which media types are supported by the client for the response.

The Tagcrumbs web service uses the HTTP Headers to let you pick a Format. This is a translation of our Formats to the media types you should use in HTTP Headers:

Format

Media Type

XML application/xml
JSON application/json
Javascript application/javascript
RSS application/rss+xml
KML application/vnd.google-earth.kmz
RDF application/rdf+xml

Model your code so that you can set those HTTP Headers at one central point and that they are included in all Requests to the Tagcrumbs API. This way, you will never have to worry about this again.

HTTP Accept Header

The HTTP protocol uses the “Accept” Header to let the client specify which media types it supports and prefers. This can be used to specify the Format of the response without using a format extension. The command line tool curl, which is available and pre-installed on many platforms, can be used to test this.

curl
curl ‘http://www.tagcrumbs.com/sascha/tagcrumbs’ -H “Accept: application/rss+xml” # this will return the RSS Representation

The server will always respond in the Format that you specify in the HTTP Accept Header. However, the format extension has a higher priority than the Accept Header.

curl
curl ‘http://www.tagcrumbs.com/sascha/tagcrumbs.json’ -H “Accept: application/rss+xml” # this will return the JSON Representation

The server will specify the current media type of the response in the HTTP Content-Type Header.

HTTP Content-Type Header

The HTTP Content-Type Header specifies which format the current request or response is in. The server will set the Content-Type header in response to your requests to show which Format is returned.

If you are sending data to the Lawi Project API with a POST or PUT Request you also have to specify the Content-Type of your current request, so that the server knows how to parse the data. If you don’t set the Content-Type our Request Forgery Protection kicks in and will block your query, resulting in a returned HTML page with an HTTP Status Code of 400 (Bad Request).