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 Store'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 Store. 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 Store 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 xmlns:thr="http://purl.org/syndication/thread/1.0"
          rel="down" 
          href="http://host-ip-address/webservice/escenic/section/1/subsections" 
          type="application/atom+xml"
          thr:count="number-of-subsections"/>   
    <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 Store'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 Store 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 Store 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.