REST API best practices¶
This page refers to REST API reference, where you can find detailed information about REST API resources and endpoints.
In order to specify a SiteAccess when communicating with the REST API, provide a custom
If it is not provided, the default SiteAccess is be used.
1 2 3 4
The methods on resources provide multiple media types in their responses.
A media type can be selected in the
Each XML media type has a unique name, e.g.
The returned XML response conforms with the complex type definition with a name, e.g.
vnd.ez.api.User in the
user.xsd XML schema definition file (see
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
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
1 2 3 4 5
In this specification, only the standard schemas and media types are defined (see
If there is only one media type defined for XML or JSON, it is also possible to specify
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.
In eZ Platform REST reference, for the sake of readability, there are no prefixes used in the URIs.
In practice, the
/api/ezp/v2 prefixes are all REST hrefs.
Remember that the URIs to REST resources should never be generated manually, but obtained from earlier REST calls.
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.