Web Services Format in Timesquare

Voir la version française

By default, all the data transferred by the Timesquare Web Services are in XML format and more precisely in Atom (RFC 4287) with Timesquare specific extensions.

It is possible to exchange data with json format. The explanations as well as the examples provided here are for XML format.

The character coding used for all the documents is UTF-8.

The schemes of those documents are described with RELAX NG fragments in compact syntax.

The URLs present in this article are not links but make it possible to identify a unique "namespace" in accordance with the standard.

Request in JSON format

It is possible to perform queries using JSON format. To do this, you must add the following HTTP headers:

• Accept: application/json (to indicate the desired format of the response)
• Content-Type: application/json (to specify the format of the request body if necessary)

The namespaces

The XML elements and attributes of Timesquare® - specific extension that appear in the “entries” and “feeds” exchanged use one of the following namespaces:

• namespace hd = "http://schemas.holydis.com/hd/2010"
• namespace tsq = "http://schemas.holydis.com/tsq/2010"

The tsq namespace is used for Timesquare® - specific elements while the hd namespace contains more generic elements and thus can be used by other Holy-Dis Web Services.

The "feed" format

Element	Description
atomAuthor	The author of the feed. For the resources where this piece of information is known, the content of the element is <name>login</name> where login is the connection name of the user, otherwise the name is “Timesquare”. The category of the resources contained in that feed. See section The categories of entries.
atomCategory	Not used.
atomContributor	Not used.
atomGenerator	Not used.
atomIcon	The feed Id (URI). This URI should not be un-referenced.
atomId	For the address of the feed, see section The links of a feed (atomLink).
atomLink	See section The links of a feed (atomLink).
atomLogo	Not used.
atomRights	Not used.
atomSubtitle	Not used.
atomTitle	A title, readable by the feed user.
atomUpdated	The date and time of the last modification of the feed. As the modification dates are not saved it is always the date and time when the feed was retrieved.
extensionElement	See in the description of each feed.
atomEntry	Each entry is an item of the collection. The default order of the entries is the reverse chronological order of the date and time of the last modification.

The links of a feed (atomLink)

Each feed has at least one link with the “self” relation that shows the URI of the feed, the one that can be used for retrieving the document or for creating a resource:

<link rel="self" href="feed_url"/>

Moreover, if the feed gives a partial view of the collection (pages), two additional links at the most will be present: one with the “next” relation which allows to get the following page and the other “previous” to get the previous page.

The OpenSearch elements

If the feed is a partial view, response elements OpenSearch 1.1 are used to specify the place of the view in the whole collection.

Element	Description
opensearch:totalResults	The total number of resources in the collection.
opensearch:startIndex	The index of the first resource present in the feed against the whole set (the first index is 1).
opensearch:itemsPerPage	The number of resources per page (feed); it is the maximum number, the last page may have less.

The format of an entry

An entry is the representation of a resource.

atomEntry = element atom:entry { atomCommonAttributes, (atomAuthor* & atomCategory* & atomContent?
& atomContributor* & atomId & atomLink* & atomPublished? & atomRights? & atomSource?
& atomSummary? & atomTitle & atomUpdated & extensionElement*) }

Elément	Description
atomCommonAttributes	Not used.
atomCategory	The category(ies) of an entry. See section The categories of entries.
atomContent	Usually the content of the entry is not used, the properties of the resource being represented as extension elements
atomContributor	Not used
atomId	The feed Id (URI). This URI should not be un-referenced. For the address of the feed, see section The links of a feed (atomLink).
atomLink	See section The links of a feed (atomLink).
atomPublished	Not used.
atomRights	Not used.
atomSource	Not used.
atomSummary	Not used.
atomTitle	A title readable by the user of the resource. It is the name under which the resource is known (name, etc.).
atomUpdated	The date and time of the last modification of the resource. As the modification dates are not saved it is always the date and time when the entry was retrieved.
extensionElement	To be read in the description of each resource.
atomAuthor	As for a feed.

The links of an entry (atomLink)

Each entry has at least one link with the "self" relation that shows the URI of the entry, the one that can be used for retrieving the document of the entry: <link rel="self" href="feed_url"/>.

Moreover, if the entry can be modified, there will be another link with the ‘edit’ relation which shows the URI that can be used to modify or delete the entry.

The categories of entries

The atom:category element in addition to the entry element classifies resources into categories. In the Atom format, categories are grouped into schemas where a schema groups related categories

Definition of the atom:category element:

atomCategory = element atom:category { atomCommonAttributes, attribute term { text }, attribute scheme { atomUri }?, attribute label { text }?, undefinedContent }

The schema used for the type of resources is http://schemas.holydis.com/hd/2010/type. The word (category identifier) is defined in the description of each collection of resources. For example: http://schemas.holydis.com/tsq/2010#personne. That word is a URI made of the URI of the namespace in which its resource is defined (tsq for the Timesquare resources) plus the name of the type as anchor of the URI.

Extension of elements of an entry (extensionElement)

These elements contain the specific properties values (for which there is no Atom representing element) of the resource. The elements which can appear in an entry are determined according to its category in the "type" schema and are defined in the "Elements" section in the description of each collection (zero or more, one or more, optional). The name of the element can be followed by "*", "+" or "?" to indicate the number of times that the element may appear; those characters have the same meaning as in the Relax NG schemas. As for the Atom elements, the order in which they appear is not important.

It should be right to apply the Atom documents in a not too rigorous way, especially to keep the possibility to meet elements or attributes different from those presented in this document. It would allow implementing clients who may face other minor format changes of the document that will appear along with Timesquare^® developments.