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
If-None-Match, but those aren't fully implemented yet in eZ Publish 5.0.
GET /content/objects/23 HTTP/1.1 Accept: application/vnd.ez.api.ContentInfo+xml
The API will reply with a few headers, as well as with the ContentInfo for content with ID 23 in XML format, as specified in the Accept header:
HTTP/1.1 200 OK Accept-Patch: application/vnd.ez.api.ContentUpdate+xml;charset=utf8 Content-Type: application/vnd.ez.api.ContentInfo+xml Content-Length: xxx
We can learn three things from those response headers:
Content-Type: application/vnd.ez.api.ContentInfo) in XML (
Accept-Patch: application/vnd.ez.api.ContentUpdate+xml;charset=utf8) it with a ContentUpdateStruct (
Accept-Patch: application/vnd.ez.api.ContentUpdate+xml;charset=utf8) in XML (
REST will use the
<?xml version="1.0" encoding="UTF-8"?> <Content href="/content/objects/23" id="23" media-type="application/vnd.ez.api.Content+xml" remoteId="qwert123"> <ContentType href="/content/types/10" media-type="application/vnd.ez.api.ContentType+xml" /> <Name>This is a title</Name> <Versions href="/content/objects/23/versions" media-type="application/vnd.ez.api.VersionList+xml" /> <CurrentVersion href="/content/objects/23/currentversion" media-type="application/vnd.ez.api.Version+xml"/> <Section href="/content/sections/4" media-type="application/vnd.ez.api.Section+xml" /> <MainLocation href="/content/locations/1/4/65" media-type="application/vnd.ez.api.Location+xml" /> <Locations href="/content/objects/23/locations" media-type="application/vnd.ez.api.LocationList+xml" /> <Owner href="/user/users/14" media-type="application/vnd.ez.api.User+xml" /> <lastModificationDate>2012-02-12T12:30:00</lastModificationDate> <publishedDate>2012-02-12T15:30:00</publishedDate> <mainLanguageCode>eng-US</mainLanguageCode> <alwaysAvailable>true</alwaysAvailable> </Content>
The XML body is a serialized version of a ContentInfo struct. Most REST API calls will actually involve exchanging XML / JSON representations of the public API. The This consistency, which we took very seriously, was a hard requirement for us, as it makes documentation much better by requiring less of it.
As explained above, the API has told us that we could modify content object 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: information fields (modified, name...) and foreign references (sectionId, mainLocationId).