Basic Principles

Representations

Representations are the supported media or MIME types of a resource. Each resource must have at least one representation. Our web service supports XML (application/xml) and JSON (application/json) by default. JSONP is not supported.

Note: We support only UTF-8 as charset encoding.

It is possible that a resource is represented by other or additional media types, e. g. a binary attachment or even multipart encoded data like a picture with a descriptive caption. Please refer to the specific documentation of a resource for related information.

A consumer application (client) must define the MIME type of the representation format by setting the specific HTTP headers:

Accept

This header defines the representation of requested data (GET) or response data (POST, PUT, DELETE). Accept header and Content-Type may differ; for example you can send data using XML (Content-Type: application/xml) and will get the response body as a JSON representation (Accept: application/json) while creating a new entity of a resource using POST. This is also valid for error messages. It is possible to get a strict representation by adding a variant to the Accept header (Accept: application/xml;strict=true or Accept: application/json;strict=true). Please note: If you request a media type that is not supported by the resource, the server will return a status code of 404 instead of 406.

Content-Type

This header is required if you want to send data to the web service (creating a new entity of a resource with POST or updating an existing entity with PUT). The Content-Type defines the MIME type of the data to send. The given MIME type must match the supported representations of the resource (and file extension is not sufficient).

Strict Representations

List resources, also known as "containers", represent lists of references (hyperlinks) to entities of a specific resource type. The URI path "/shortlist" represents a list of shortlists of an user: an unique identifier is missing. Such a container would return only a list with references and required information.

Note: Under development. This information does apply to selected resources only.

List resources, also known as "containers", represent lists of references (hyperlinks) to entities of a specific resource type. The URI path "/shortlist" represents a list of shortlists of an user: an unique identifier is missing. Such a container would return only a list with references and required information.

 

<entries>

<entry id="1" xlink:href="/qualified/path/to/entry/1" mimeType="..." /> <entry id="2" xlink:href="/qualified/path/to/entry/2" mimeType="..." />

...

</entries>

 

An entity can also contain references to other resources. The URI path "/shortlist/0" represents such an entity: a shortlist with the ID 0.

 

<entry id="1">

<title>a title<title>

...

<anotherEntry id="123" xlink:href="/qualified/path/to/anotherentry/123" mimeType="..." />

...

</entry>

 

By default our API delivers a full representation, even on list representations. Because this, a list entry as shown above can contain child notes and additional information - not only the reference and id. This is a business decision to minimize API calls for selected use cases and differs from the REST approach.

If a client only needs a list of references, e. g. to reduce traffic and the data volume, a "strict representation" is required. To get this strict variant, the client must extend the Accept header with the variant "strict=true":

Accept: application/xml;strict=true

or for a strict JSON representation

Accept: application/json;strict=true

 

Without the strict variant, the list example would look like this (full representation):

 

<entries>

<entry id="1">

<title>entry 1<title>

...

<anotherEntry id="123" xlink:href="/qualified/path/to/anotherentry/123" mimeType="..." />

...

</entry>

<entry id="2">

<title>entry 2<title>

...

<anotherEntry id="456" xlink:href="/qualified/path/to/anotherentry/456" mimeType="..." />

...

</entry>

...

</entries>