Par défaut, toutes les données transférées par les Web Services Timesquare sont en format XML et plus précisément en format Atom (RFC 4287) avec des extensions qui sont particulières à Timesquare.
Il est possible d'échanger des données avec le format json. Les explications ainsi que les exemples fournis sont pour le format XML.
Le codage de caractères utilisé pour tous les documents est UTF-8.
Les caractères spéciaux suivants ne sont pas supportés : <, >, &, ", '
Si je souhaite utiliser ces caractères dans les données textuelles XML :
- & doit être remplacé par &
- < doit être remplacé par <
- > doit être remplacé par >
- " doit être remplacé par "
- ' doit être remplacé par '
Les schémas de ces documents sont décrits avec des fragments de RELAX NG en syntaxe compacte.
Les URL présentes dans cette article ne sont pas des liens mais permettent d’identifier un "namespace" unique conformément à la norme.
Requête au format JSON
Il est possible d'effectuer des requêtes en utilisant le format JSON. Pour ce faire, il faut ajouter les en-tête HTTP suivants :
- Accept : application/json (pour indiquer le format souhaité de la réponse)
- Content-Type : application/json (pour spécifier le format du corps de la requête si besoin)
Les namespaces
Les éléments et attributs XML d'extension spécifiques à Timesquare qui apparaissent dans les "entries" et "feeds" échangés utilisent un des namespaces suivant :
- namespace hd = "http://schemas.holydis.com/hd/2010"
- namespace tsq = "http://schemas.holydis.com/tsq/2010"
Le namespace tsq est utilisé pour des éléments spécifiques à Timesquare tant que le namespace hd contient des éléments qui sont plus génériques et qui donc peuvent être utilisés par d'autres Web Services Holy-Dis.
Le format d’un "feed"
| Elément | Description |
|---|---|
| atomAuthor | L'auteur du feed. Pour les ressources où cette information est connue, le contenu de l'élément est <name>login</name> ou login est le nom de connexion de l'utilisateur, sinon le nom est "Timesquare". |
| atomCategory | La ou les catégories des ressources contenues dans ce feed. Voir les catégories des entries. |
| atomContributor | Non utilisé. |
| atomGenerator | Non utilisé. |
| atomIcon | Non utilisé. |
| atomId | L'identifiant du feed (un URI). Cet URI ne doit pas être de-référencé. Pour l'adresse du feed, voir les links d'un feed (atomLink). |
| atomLink | Voir les links d'un feed (atomLink). |
| atomLogo | Non utilisé. |
| atomRights | Non utilisé. |
| atomSubtitle | Non utilisé. |
| atomTitle | Un titre lisible par l’utilisateur du feed. |
| atomUpdated | La date et l'heure de la dernière modification du feed. Comme les dates de modification ne sont pas stockées, c'est toujours la date et l'heure de la récupération du feed. |
| extensionElement | A voir dans la description de chaque feed. |
| atomEntry | Chaque entry est un élément de la collection. L'ordre par défaut des entries est l'ordre chronologique inverse de la date et l'heure de la dernière modification. |
Les links d'un feed (atomLink)
Chaque feed a au moins un link avec la relation "self" qui dénote l'URI du feed, celui qui peut être utilisé pour récupérer le document ou pour créer une ressource :
<link rel="self" href="feed_url"/>
En plus, si le feed présente une vue partielle de la collection (pagination), au plus, deux links supplémentaires vont être présents : un avec la relation "next" pour avoir la page suivante et l'autre avec "previous" pour avoir la page précédente.
Les éléments OpenSearch
Si le feed est une vue partielle, des éléments de réponse OpenSearch 1.1 sont utilisés pour spécifier la place de la vue par rapport à la collection entière.
| Elément | Description |
|---|---|
| opensearch:totalResults | Le nombre total de ressources dans collection. |
| opensearch:startIndex | L'index de la première ressource présente dans le feed par rapport à toute la collection (le premier index est 1). |
| opensearch:itemsPerPage | Le nombre de ressources par page (feed). C'est le nombre maximum. S'il s'agit de la dernière page, il peut y en avoir moins. |
Le format d'une entry
Une entry est la représentation d'une ressource.
atomEntry = element atom:entry { atomCommonAttributes, (atomAuthor* & atomCategory* & atomContent?
& atomContributor* & atomId & atomLink* & atomPublished? & atomRights? & atomSource?
& atomSummary? & atomTitle & atomUpdated & extensionElement*) }
| Elément | Description |
|---|---|
| atomCommonAttributes | Non utilisé. |
| atomCategory | La ou les catégories de l'entry. Voir les catégories des entries. |
| atomContent | Le contenu de l'entry. N'est pas utilisé normalement, les propriétés de la ressource étant représentés comme des éléments d'extension. |
| atomContributor | Non utilisé. |
| atomId | L'identifiant du feed (un URI). Cet URI ne doit pas être de-référencé. Pour l'adresse du feed, voir les links d'un feed (atomLink). |
| atomLink | Voir les links d'un feed (atomLink). |
| atomPublished | Non utilisé. |
| atomRights | Non utilisé. |
| atomSource | Non utilisé. |
| atomSummary | Non utilisé. |
| atomTitle | Un titre lisible par l'utilisateur de la ressource. C'est le nom sous lequel la ressource est connue (le libellé, le nom, etc.). |
| atomUpdated | La date et l'heure de la dernière modification de la ressource. Comme les dates de modification ne sont pas stockées, c'est toujours la date et l'heure de la récupération de l'entry. |
| extensionElement | A voir dans la description de chaque ressource. |
| atomAuthor | Comme pour un feed. |
Les links d'une entry (atomLink)
Chaque entry a au moins un link avec la relation « self » qui dénote l'URI de l'entry, celui qui peut être utilisé pour récupérer le document du entry : <link rel="self" href="feed_url"/>.
En plus, si l'entry est modifiable, il va y avoir un autre link avec la relation « edit » qui dénote l'URI qui peut être utilisé pour modifier ou supprimer l'entry.
Les catégories des entries
L’élément atom:category en plus de l’élément entry permet de classifier les ressources en catégories. Dans le format Atom, les catégories sont groupées dans des schémas où un schéma regroupe des catégories apparentées.
La définition de l'élément atom:category :
atomCategory = element atom:category { atomCommonAttributes, attribute term { text }, attribute scheme { atomUri }?, attribute label { text }?, undefinedContent }
Le schéma utilisé pour le type des ressources est http://schemas.holydis.com/hd/2010/type. Le terme (l'identifiant d'une catégorie) est défini dans la description de chaque collection de ressources. Par exemple : http://schemas.holydis.com/tsq/2010#personne. Ce terme est un URI qui est composé de l'URI du namespace dans lequel la ressource est définie (tsq pour les ressources Timesquare) plus le nom du type comme ancre (anchor) de l'URI.
Les éléments d'extension d'une entry (extensionElement)
Ces éléments contiennent les valeurs des propriétés spécifiques (pour lesquelles il n'y a pas d'élément Atom pour les représenter) de la ressource. Les éléments qui peuvent apparaître dans une entry sont déterminés par sa catégorie dans le schema "type" et ils sont définis dans la section "Éléments" dans la description de chaque collection. Le nom de l'élément peut être suivi de "*", "+" ou "?" pour désigner le nombre de fois que l'élément peut apparaître (zero ou plus, un ou plus, optionnel respectivement). Ces caractères ont la même signification que dans les schémas Relax NG. Comme pour les éléments Atom, l'ordre dans laquelle ils apparaissent n'a pas d'importance.
Il est souhaitable d'interpréter de façon laxiste des documents Atom, notamment ne pas exclure la possibilité de rencontrer d'autres éléments ou attributs que ceux présentés dans ce document. Cela permet d'implémenter des clients qui peuvent faire face aux changements mineurs dans le format des documents qui peuvent apparaître avec l'évolution de Timesquare.
Commentaires
0 commentaire
Vous devez vous connecter pour laisser un commentaire.