Introduction aux Web Services

View the English version

Présentation des Web Services

Le formalisme des services repose sur le standard Atom qui se réfère à deux standards :

• Le Format de Syndication Atom qui est un format de document XML destiné à représenter un flux de contenu (news, blog-posts, ou dans le cas de Timesquare, des personnes, des plannings, etc).
• Le protocole de publication Atom (AtomPub ou APP), un protocole basé sur HTTP pour créer ou mettre à jour des ressources web.

Le protocole employé qui véhicule les ressources web au sein de l’application utilise HTTP pour gérer des données au format Atom, et respecte ainsi les principes d’architecture REST (REpresentational State Transfer).

Entre autres :

• On appelle ressource n’importe quel objet accessible en ligne et identifiable via une IRI (Internationalized Resource Identifier).
• AtomPub permet de créer, lister, mettre à jour et supprimer des ressources.
• Les ressources peuvent être regroupées dans des collections.

Une collection est un ensemble de liens vers des ressources.

• La représentation d’une collection ou d’une ressource constitue un flux Atom appelé aussi feed.
• Un flux Atom (ou feed) contient une liste d’items Atom.
• Un item Atom est appelé Entry: il s’agit de la représentation d’un contenu, généralement un élément de donnée web.

Il est possible d'envoyer jusqu'à 10 requêtes maximum par seconde.

Pré-requis : création d'un token

Pour accéder aux Web Services, un token est nécessaire. Il sert à l'authentification en lieu et place d'un user / mot de passe. Un utilisateur authentifié sur Timesquare et/ou sur My Timesquare n’a pas accès aux Web Services.

La suppression du token n'est autorisé que par son créateur.

 Configuration / Autorisations / Web Services

Pour créer un token, je saisis un libellé et je clique sur le bouton Ajouter. Le nouveau token est créé. Pour l’utiliser, je le copie. Une fois créé, il n'est plus possible de le récupérer sauf à l'avoir sauvegardé par ailleurs.

Exemple de token

Token généré avec Timesquare

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOlsidGltZXNxdWFyZVJlc3RBUEkiXSwicmV2b2thYmxlIjp0cnVlLCJ1c2VyX25hbWUiOiJURUNITklRVUVfV1MiLCJzY29wZSI6WyJyZWFkIiwid3JpdGUiXSwidXNyaWQiOjMsImF1dG1kIjoiVVRJTElTQVRFVVIiLCJhZG0iOnRydWUsImV4cCI6MzI1MDM2NzYzOTksImp0aSI6IjAxM2IxYThmLTE3MDEtNGYwMi1hMTQyLTA2OGZhMjcwNWI5YyIsImNsaWVudF9pZCI6InRzcSJ9.Eo_yfpeMGDUQxLai2KZ7n3tL4-ajme00hQaJsMFnRiVa4aloEkS-0XdzBSTF_REA1xt5WZc5bwzgM8ILuRfCoH_aUIHWn_jBN1LrfySL5SBguMkT4Dhe9V04T0TegByC6zaH-isw97ROIqw0Sl_CYmA3j1vkAB3GO_URI5Oi0s4

Validité du token

Le token créé dans le cadre des Web Services est permanent, il n'est donc pas nécessaire de le re-créer régulièrement. En cas de besoin, il est possible de révoquer un token en le supprimant de la liste depuis Configuration / Autorisations / Web Services.

Intégration du token

Le token doit être intégré dans la valeur de l’entête « Authorization », en le préfixant de « Bearer » : Authorization : Bearer <token>

Illustration par la pratique

Reportez-vous aux fichiers XML pour consulter des exemples.

Scénario d’un échange classique

1. Envoi d'une requête GET à l'adresse d'un service.
2. Le serveur répond par la liste des collections disponibles, éventuellement regroupées en workspaces.
3. Envoi d'une requête GET à l'adresse d'une collection.
4. Le serveur répond avec un flux (feed Atom) listant les éléments de la collection (la liste peut être partielle et paginable. Elle contiendra dans ce cas des liens vers les URI des pages précédente et suivante).
5. L’utilisateur crée une nouvelle ressource à l'intérieur d'une collection en postant (requête POST) un document à l'adresse de la collection.
6. Le serveur répond avec l'adresse de la ressource créée.
7. L’utilisateur peut alors gérer la ressource en envoyant GET, PUT ou DELETE à son adresse.

Rechercher une personne par son matricule

GET /[Url_de_base]/api/feed/personnes?matricule=9876543210

Modifier le dossier d'une personne

PUT /[Url_de_base]/api/feed/personnes/19000

Consulter le planning initial d'une personne

GET /[Url_de_base]/api/feed/personnes/19000/plannings_prev?datetime-min=2019-01-12&datetime-max=2019-01-18

Codes réponses et messages d'erreur

Les Web Services répondent à chaque requête par un code réponse HTTP. Les messages d'erreur sont renvoyés en HTML.

Les codes réponse disponibles sont les suivants :

• 200 OK : La requête est acceptée. La réponse contient le résultat. Ce code réponse général peut être renvoyé pour n'importe quelle requête. Pour les requêtes GET, la ressource ou les données requêtées se trouvent dans le corps de la réponse. Pour les requêtes PUT ou DELETE, la requête a abouti et des informations sur le résultat (tels que les identificateurs de nouvelles ressources et les modifications du statut des ressources) se trouvent dans le corps de la réponse.
• 204 NO CONTENT : La requête est acceptée. Il n'y a pas de contenu à envoyer dans le corps de la réponse.
• 400 BAD REQUEST : La requête n'est pas valide. Elle est mal écrite. Ce code est renvoyé lorsque le serveur tente de traiter la requête, mais que des aspects de cette requête ne sont pas valides. Ce code indique également une erreur fonctionnelle en écriture.
• 404 NOT FOUND : La ressource ciblée n'existe pas. L'URI est peut-être incorrect ou la ressource a peut-être été supprimée.
• 500 INTERNAL SERVER ERROR : Une erreur technique interne s'est produite sur le serveur. Il s'agit peut-être d'un incident lié à la requête ou d'un incident lié au code côté serveur.

Références

Pour en savoir plus :

• Le format ATOM
• Le protocole ATOMPub

Fuseaux horaires

Seule la lecture dans un autre fuseau horaire est possible. L’écriture se fera toujours dans le fuseau horaire de l’élément de planification concerné. Exemple : le fuseau horaire du calendrier pour une personne ou pour une tâche.

Pour renvoyer les données en fonction d’un fuseau horaire en particulier, il faut ajouter en en-tête de la requête le paramètre "User-TimeZoneId" avec comme valeur l’identifiant du fuseau horaire en question. Par exemple "Asia/Tbilisi" pour le fuseau horaire Tbilisi. En l’absence du paramètre en en-tête, les données sont renvoyées brutes (dans le fuseau horaire de l’élément de planification concerné).

L’ensemble des identifiants de fuseaux horaires possibles est visible dans la table TIMEZONE.

Les périodes renvoyées par les différents Web Services prennent en compte l’offset de Timezone.

Exemple pour une période dans le fuseau Asia/Tbilissi :
<tsq:periode debut="2021-11-01T17:00:00+04:00" fin="2021-11-01T21:00:00+04:00"/>