REST API best practices¶
This page refers to REST API reference, where you can find detailed information about REST API resources and endpoints.
Specifying SiteAccess¶
In order to specify a SiteAccess when communicating with the REST API, provide a custom X-Siteaccess
header.
If it is not provided, the default SiteAccess is be used.
Example:
1 2 3 4 |
|
Media types¶
The methods on resources provide multiple media types in their responses.
A media type can be selected in the Accept
header.
Each XML media type has a unique name, e.g. application/vnd.ibexa.api.User+xml
.
The returned XML response conforms with the complex type definition with a name, e.g. vnd.ibexa.api.User
in the user.xsd
XML schema definition file (see User_
).
To derive the implicit schema of the JSON from the XML schema a uniform transformation from XML to JSON is performed as shown below.
1 2 3 4 5 6 7 8 |
|
Transforms to:
1 2 3 4 5 6 7 8 9 10 11 12 13 |
|
Different schemas that induce different media types on resource can be used to allow making specific representations optimized for purposes of clients. It is possible to make e.g. a new schema for mobile devices for retrieving an article.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
|
So that:
1 2 |
|
Returns:
1 2 3 4 5 |
|
In this specification, only the standard schemas and media types are defined (see InputOutput_
).
If there is only one media type defined for XML or JSON, it is also possible to specify application/xml
or application/json
.
URIs¶
The REST API is designed in such a way that the client doesn't need to construct any URIs to resources.
Starting from the root resources (ListRoot_
) every response includes further links to related resources.
The URIs should be used directly as identifiers on the client side and the client should not construct any URIs by using an ID.
URIs prefix¶
In REST reference, for the sake of readability, there are no prefixes used in the URIs.
In practice, the /api/ibexa/v2
prefixes are all REST hrefs.
Remember that the URIs to REST resources should never be generated manually, but obtained from earlier REST calls.
OPTIONS requests¶
Any URI resource that the REST API responds to will respond to an OPTIONS request.
The response contains an Allow
header, that as specified in chapter 14.7 of RFC 2616 lists the methods accepted by the resource.
1 2 |
|
1 2 |
|