As explained in the introduction, the REST API is based on a very limited list of general = principles:
This verb is used to query the API for information. It is one of the two= operations web browsers implement, and the most commonly used.
The only requirement for this verb is usually the resource URI, and the =
accept header. On top of that, cache request headers can be added, like
GET /content/objects/23 HTTP/1.1 Accept: application/vnd.ez.api.ContentInfo+xml=20
The API will reply with:
HTTP/1.1 200 OK Accept-Patch: application/vnd.ez.api.ContentUpdate+xml;charset=3Dutf8 Content-Type: application/vnd.ez.api.ContentInfo+xml Content-Length: xxx=20
The length of our content, provided by the Content-Length header, isn't&= nbsp;that useful.
The API responded here with a standard 200 OK HTTP response code, which = is the expected response code for a "normal" GET request. Some GET requests= , like getting a content's= current version, may reply with a 301 Moved permanently, or 307 Tempor= ary redirect code.
Errors will be indicated with HTTP error codes, like 404 for Not Found, = or 500 for Internal server error. The REST specifications provide the = list of every HTTP response code you can expect from implemented resources.=
As long as a response contains an actual HTTP body, the Content-Type hea=
der will be used to specify which Content-Type is contained in the response=
. In that case, a ContentInfo (Content-Type: application/vnd.ez.=
api.ContentInfo) in XML (Content-Type: a=
pplication/vnd.ez.api.ContentInfo+xml)
This is a very interesting one.
It tells us we can modify the received content by patching (Accept-Patch: application/vnd.ez.api.ContentUpdate=
+xml;charset=3Dutf8) in XML (Accept-Patch: app=
lication/vnd.ez.api.ContentUpdate+xml;charset=3Dutf8) format. Of course, JSON would also work, with the proper format.
This last part means that if we send a PATCH /content/objects/23 request= with a ContentUpdateStruct XML payloa= d, we will update this Content.
REST will use the Accept-Patch header to i=
ndicate you how to modify the returned data.
Depending on the resource, request & response headers will vary. For=
instance, creating content, or getting a content's curr=
ent version will both send a Location header to provi=
de you with the requested resource's ID.
Those particular headers generally match a specific list of HTTP respons=
e codes. Location is sent by 201 Created, 301 Moved perm=
anently, 307 Temporary redirect responses. This list is=
n't finished, but you can expect those HTTP responses to provide you with a=
Location header.
This request header is the request counterpart of the Location response = header. It is used in a COPY / MOVE operation, like copying a Content, on a resource to indicate where the re= source should be moved to, using the ID of the destination.
<?xml version=3D"1.0" encoding=3D"UTF-8"?>=
;
<Content href=3D"/content/objects/23" id=3D"23"
media-type=3D"application/vnd.ez.api.Content+xml" remoteId=3D"qwert123"&g=
t;
<ContentType href=3D"/content/types/10" media-type=3D"application/vnd.=
ez.api.ContentType+xml" />
<Name>This is a title</Name>
<Versions href=3D"/content/objects/23/versions" media-type=3D"applicat=
ion/vnd.ez.api.VersionList+xml" />
<CurrentVersion href=3D"/content/objects/23/currentversion"
media-type=3D"application/vnd.ez.api.Version+xml"/>
<Section href=3D"/content/sections/4" media-type=3D"application/vnd.ez=
.api.Section+xml" />
<MainLocation href=3D"/content/locations/1/4/65" media-type=3D"applica=
tion/vnd.ez.api.Location+xml" />
<Locations href=3D"/content/objects/23/locations" media-type=3D"applic=
ation/vnd.ez.api.LocationList+xml" />
<Owner href=3D"/user/users/14" media-type=3D"application/vnd.ez.api.Us=
er+xml" />
<lastModificationDate>2012-02-12T12:30:00</lastModificationDate&=
gt;
<publishedDate>2012-02-12T15:30:00</publishedDate>
<mainLanguageCode>eng-US</mainLanguageCode>
<alwaysAvailable>true</alwaysAvailable>
</Content>=20
The XML body is a serialized version of a ContentInfo<= /a> struct. Most REST API calls will actually involve exchanging XML / JSON= representations of the public API. This consistency, which we took very se= riously, was a hard requirement for us, as it makes documentation much bett= er by requiring less of it.
As explained above, the API has told us that we could modify content obj=
ect 23 by sending a vendor/application/vnd.ez.ContentUpdate+xml. This media type again matches a Value in the API, ContentUpdateStruct.
The REST API data structs mostly match a PHP Public API value object
Value objects like ContentInfo basically feature two = types of fields: basic, local fields (modified, name...) and foreign field(= s) references (sectionId, mainLocationId).
Local fields will be represented in XML / JSON with a primitive type (in=
teger, string), while foreign key references will be represented as a link =
to another resource. This resource will be identified with its URI (/=
content/objects/23/locations), and the media-type that should be req=
uested when calling that resource (media-type=3D"application/vnd.ez.a=
pi.LocationList+xml"). Depending on how much data you need, you may =
choose to crawl those relations, or to ignore them.
XSD files
For each XML structure known to the REST API, you can find XSD files in = the XSD folder of the specifications. Those will allow you to validate your= XML, and learn about every option those XML structures feature.
https://git= hub.com/ezsystems/ezpublish-kernel/tree/master/doc/specifications/rest/xsd<= /a>So far, we have seen that responses will depend on:
URI parameters are of course also used. They usually serve as filters / = options for the requested resource. For instance, they can be used to custo= mize a list's offset/limit, to filter a list, specify which fields you want= from a content... For almost all resources, those parameters must be = provided as GET ones. This request would return the 5 first relations for V= ersion 2 of Content 59:
GET /content/objects/59/versions/2/relations&limit=3D5 HTTP/1.1 Accept: application/vnd.ez.api.RelationList+xml=20
Working with value objects IDs
Resources that accept a reference to another resource expect this refere=
nce to be given as a REST ID, not a Public API ID. As such, the URI to requ=
est users that are assigned the role with ID 1 would be GET /api/ezp/=
v2/user/users?roleId=3D/api/ezp/v2/user/roles/1.
In addition to the usual GET, POST, PUT and DELETE HTTP verbs, the API s=
upports a few custom ones: COPY, MOVE (http://tools.ietf.org/h=
tml/rfc2518), PATCH (http://tools.ietf.org/html/rfc5789) and PUBLISH. While it should generally not be a problem, some HTTP =
servers may fail to recognize those. If you face this situation, you can cu=
stomize a standard verb (POST, PUT) with the X-HTTP-Method=
-Override header.
POST /content/objects/59 HTTP/1.1 X-HTTP-Method-Override: PATCH=20
Both methods are always mentioned, when applicable, in the specifi= cations.
One of the principles of REST is that the same resource (Content, Locati= on, ContentType, ...) should be unique. The purpose is mostly to make it si= mple to cache your REST API using a reverse proxy like Varnish. If the same= resource is available at multiple locations, cache purging becomes much mo= re complex.
Due to this, we decided not to enable siteaccess matching with REST. In =
order to specify a siteaccess when talking to the REST API, a custom header=
, X-Siteaccess, needs to be provided. If it isn't, the de=
fault one will be used:
GET / HTTP/1.1 Host: api.example.com Accept: application/vnd.ez.api.Root+json X-Siteaccess: ezdemo_site_admin=20