How The Web Service Works
This section contains a brief general description of how a client application is expected to make use of the Content Engine's web service.
Assuming the client has no information about the web service or
what it can provide, it can initiate contact by sending an HTTP
GET
request to the web service's "start" URI. This is
usually
http://host-ip-address/webservice/escenic/section/ROOT/subsections
where host-ip-address is the host name
or IP address of the Content Engine. This "start address" (plus a user name and
password) is the minimum information a client needs to be able to
interact at some level with the web service. The following
curl
command, therefore, will initiate contact with a
Content Engine
web service:
curl -u user:password -X GET http://host-ip-address/webservice/escenic/section/ROOT/subsections
The web service responds to such a request by returning a feed resource: an ATOM feed document that looks something like this:
<feed xmlns="http://www.w3.org/2005/Atom"> <author> <name>Escenic Content Engine</name> </author> <id>http://host-ip-address/webservice/escenic/section/ROOT/subsections</id> <link rel="self" href="http://host-ip-address/webservice/escenic/section/ROOT/subsections" type="application/atom+xml"/> <updated>2010-06-23T16:51:06.721Z</updated> <title type="text">Publication root sections you are authorized to.</title> <link rel="changelog" href="http://host-ip-address/webservice/escenic/changelog" type="application/atom+xml"/> <entry> <id>http://host-ip-address/webservice/escenic/section/1</id> <title type="text">frontpage</title> <updated>2010-06-22T10:16:46.309Z</updated> <category term="directory" scheme="http://www.vizrt.com/types"/> <link rel="edit-media" type="application/vnd.escenic.content+xml;type=com.escenic.section" href="http://host-ip-address/webservice/escenic/section/1"/> <link rel="down" href="http://host-ip-address/webservice/escenic/section/1/subsections" type="application/atom+xml"/> <link rel="http://www.vizrt.com/types/relation/inboxes" href="http://host-ip-address/webservice/escenic/section/1/inboxes" type="application/atom+xml"/> <link rel="http://www.vizrt.com/types/relation/lists" href="http://host-ip-address/webservice/escenic/section/1/lists" type="application/atom+xml"/> <link rel="http://www.vizrt.com/types/relation/pages" href="http://host-ip-address/webservice/escenic/section/1/pages" type="application/atom+xml"/> <link rel="http://www.vizrt.com/types/relation/content-items" href="http://host-ip-address/webservice/escenic/section/1/content-items" type="application/atom+xml"/> <link rel="http://www.vizrt.com/types/relation/changelog" href="http://host-ip-address/webservice/escenic/changelog/section/1" type="application/atom+xml"/> </entry> </feed>
The document contains a series of entry
elements representing the root sections of all the Content Engine's
publications. Each entry contains a sequence of link elements
representing the resources to which the requesting user has access. In
the example, above, for example, the requesting user has access rights
to many resources in the publication "Escenic Times", but not to
"frontpage Test".
A link
element has three attributes:
href
-
The URI of a resource.
type
-
This attribute contains a MIME type id identifying the type of data the resource contains. The MIME type
application/atom+xml
, for example, indicates that the resource is another ATOM feed document. All the types used by the Content Engine web service are described in Supported MIME Types. rel
-
This attribute describes the meaning of the resource in terms of its relationship to the current resource. All the link relations used by the Content Engine web service are described in Supported Link Relations.
These three attributes provide the client application with sufficient information to determine:
-
Which resource (if any) it needs to access next
-
The URL needed to access the resource
-
What kind of data it can expect to find in the resource.
The client can construct a new GET
request from
the information returned in this document and obtain a new feed
resource. It can, for example obtain a feed containing links to all the
top-level sections in the Escenic Times publication by submitting the
following request:
curl -u user:password -X GET http://host-ip-address/webservice/escenic/section/22/subsections
By recursively retrieving feed resources in this way, it is possible to navigate down through the section tree, then from a section to a list of in-boxes, for example, from there to a specific in-box. At various points along this route you can also retrieve feed resources that list links to actual content items (The content items in a section, for example, or the content items in a list or in-box). By following these links you can retrieve entry resources that represent actual content items, and media resources such as image files.
The web service allows entry and media resources to be modified by
users with sufficient privileges. This is done by submitting requests
using HTTP PUT
, POST
and
DELETE
operations:
-
The client can update an entry or media resource by submitting a PUT request containing a modified resource and the URI of the resource to be updated.
-
The client can create a new entry or media resource by submitting a POST request containing a new resource and the URI of the Atom collection (i.e feed resource) to which it is to be added.
-
The client can delete an entry or media resource by submitting a DELETE request containing the URI of the resource to be deleted.