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.

Code Description
200 OK Requête acceptée et il doit y avoir du contenu, considérez que l’opération est terminée
202 Accepted Requête acceptée, mais le traitement n’est pas terminé. L’en-tête d’emplacement pointe vers une URL qui indique la progression ou le résultat final
204 No Content Requête acceptée, mais il n’y a pas plus de détails/contenu à ce sujet, considérez que l’opération est terminée
302 Found Pour rediriger vers une autre URL, comme un téléchargement
400 Bad Request Requête mal formatée, c’est-à-dire que le JSON n’est pas valide, contrairement à un échec de validation (champ obligatoire manquant, date qui n’est pas une date), qui correspond au code 422
401 Unauthorized Pas d’en-tête d’autorisation, ou non autorisé
403 Forbidden L’utilisateur n’a pas l’autorisation
404 Not Found Si une ressource ou une page spécifique n’est pas trouvée, c’est-à-dire hwr/account/blah. Dans le cas des appels de liste (c’est-à-dire GET /hwrruns), un tableau vide sera renvoyé
409 Conflict En général, il y a une collision à la création (POST), reportez-vous aux API pour les détails
412 Precondition Failed En général, il y a un problème de modification de la ressource à la mise à jour (PUT/PATCH), reportez-vous aux API pour les détails
422 Unprocessable Entity La syntaxe de la requête est correcte, mais l’entité n’est pas valide, un champ obligatoire est manquant ou une date est hors de la plage
5xx Erreur interne du serveur

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.

type desc
string (chaîne) string (chaîne)
int int
float (flottant) float (flottant)
bool boolean (booléen)
Object array (Tableau d’objets) Un tableau d’éléments de type Object (Objet)
uuid UUID entre guillemets. « 3287912374838239853 »
date ISO 8601 entre guillemets. « 2015-02-03T13:04:24Z »
email (courriel) adresse de courriel entre guillemets (limite de 254). « frank@example.com« 
url URL entre guillemets, peut être relative. « /v1/svc/3323 »

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

param type desc
offset int Décalage de numéro d’enregistrement, en commençant par 0. Le premier numéro d’enregistrement après ce décalage est inclus dans les résultats. Valeur par défaut : 0
limit int Nombre maximal d’enregistrements à renvoyer, jusqu’à un maximum de 100. Il est possible que moins d’enregistrements soient renvoyés. Valeur par défaut : 50
trier string (chaîne) Champ selon lequel trier
dir enum desc | asc. Valeur par défaut : desc

Objet de réponse

propriété type desc
total int le nombre total dans l’ensemble
from int le numéro d’enregistrement du premier élément dans les résultats. Les numéros d’enregistrement démarrent à 1
à int le nombre d’enregistrements du dernier élément des résultats
résultats Object array (Tableau d’objets) un tableau des objets de résultat; voir API pour le type d’objet. Ce sera un tableau vide si le total est de 0. Il peut également être vide s’il n’y a aucun résultat qui commence au décalage demandé
{  
  "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.

État HTTP Code API args desc
400 E-API-400 code d’état Un problème interne causé par une mauvaise requête
400 E-API-450 lineNbr, colNbr Exception de traitement JSON générale
400 E-API-451 lineNbr, colNbr L’analyse JSON a échoué. JSON mal conçu
400 E-API-452 lineNbr, colNbr Mappage JSON
400 E-API-453 lineNbr, colNbr Génération de JSON. Impossible de générer une réponse JSON
406 E-API-406 Le type de média d’acceptation de réponse n’est pas pris en charge
415 E-API-415 Le type de média de la requête de type Contenu n’est pas pris en charge
422 E-API-422 property:error, … Échec de validation. Voir API pour la description des propriétés d’objet requises
500 E-API-500 Erreur interne du serveur

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.

Get Support

Knowledge Base

User Guide
Follow via Email

Enter your email address to get new content notifications by email.

%d bloggers like this: