API de zone commune de services

Aperçu des API
Les API de services Web de BEACON utilisent des services Web RESTful pour fournir des données au format JSON. La plupart des environnements de programmation disposent de bibliothèques facilement accessibles permettant de créer des requêtes HTTP et d’analyser les réponses.

API de zone commune de services

Tous les services Web de BEACON Web suivent la conception d’API de zone commune de services.

Codes d’état HTTP

Il s’agit des codes de réponse standard que tous les services BEACON renvoient. Reportez-vous à chaque API pour obtenir des détails spécifiques à propos des codes.

Objets de réponse

Tous les services répondent sans ambiguïté de type d’objet, c’est-à-dire qu’un client pourra obtenir de manière déterministe une réponse en fonction du code de réponse HTTP. Selon le code de réponse HTTP, le même objet est renvoyé. Certaines réponses utilisent des « wrappers » d’objets pour la pagination.

Lorsqu’une API renvoie des codes 4xx, il s’agit de réponses d’erreur standard.

Un code 2xx renvoie un objet JSON conformément à l’API.

Noms de propriétés

Tous les objets JSON utilisent la casse mixte, sauf les uuids qui sont la propriété avec UUID en suffixe, comme accountUUID, reportUUID, taskUUID, etc.

Pagination

L’API permet de paginer les ensembles de résultats. Les résultats paginés sont renvoyés dans un objet wrapper de pagination, avec les objets sous une propriété de résultats. La requête d’API doit inclure un ensemble de paramètres standard qui indique les critères de pagination.

Paramètres

Objet de réponse

{  
  "total": 532,
  "from": 101,
  "to": 150,
  "results": [ {
    MY OBJECT
  ]}
}

Codes API
Tous les services utilisent un format de code API commun :

apicode:= [E|W|I|D]-tla-nnn

Chaque service définit les codes d’erreur possibles et leurs significations.

Par exemple, E-HWR-200 ou W-TSK-56

Arguments de code

Certains codes peuvent nécessiter des arguments. Vous pouvez les utiliser lorsque vous créez un message d’erreur, par exemple le code E-HWR-301 peut se traduire en français par « Le modèle cloné ({1}) n’existe pas », où {1} est la première valeur d’argument, par exemple « Exécution en hiver ».

La propriété args facultative dans la réponse d’erreur est un tableau de chaînes.

Codes de raisons

Les codes de raisons sont des points non lisibles par l’homme dans le code qui indiquent l’emplacement du code d’API ou la raison sous-jacente de la génération du code. Ils peuvent être attachés et un service doit faire suivre les codes de raison : si le service HWR appelle le service TSK, qui renvoie un code d’erreur et de raison, le service HWR doit renvoyer un nouveau code d’API (E-HWR-nnn) et attacher le code de raison TSK (HWR-client.tsk_TSK-run.py:56)

reason:= tla-msg[_reason]*
msg:= anyalpha ^_

Error Responses

Un service qui renvoie des erreurs répond avec un objet standard qui contient au moins le code et la raison.

{
  "code": "E-HWR-200",
  "args": ["a code argument"],
  "reason": "HWR-client.tsk_TSK-run.py:56
}

Codes d’API communs

Ces codes sont communs à tous les services.

Authentification

L’API utilise l’authentification d’accès de base HTTP pour fournir à vos applications un accès sécurisé à toutes les données disponibles sur votre compte. De plus, toutes les requêtes doivent passer par notre point de terminaison HTTPS, où tous les transferts de données sont chiffrés par SSL. Avec votre nom d’utilisateur et votre mot de passe BEACON, vous pouvez utiliser la méthode base64 de votre bibliothèque de programmation pour créer un en-tête d’autorisation HTTP. Pour consulter une explication de cette procédure, reportez-vous à : http://en.wikipedia.org/wiki/Basic_access_authentication.