Partage de données entre systèmes

Authentification

Chaque demande d'API envoyée par une application tierce au site Web du Centre de commande sera authentifiée et autorisée comme si un utilisateur réel utilisait le logiciel. Les autorisations de groupe de l'utilisateur associé à la demande d'API détermineront les champs et les employés que chaque demande d'API est autorisée à afficher et / ou à modifier.

Pour utiliser l'API, chaque utilisateur doit avoir une ou plusieurs clés d'API secrètes identifiant cet utilisateur auprès de l'API. La clé secrète de l'API est un nombre de 160 bits exprimé sous forme hexadécimale. Il s'agit d'un nombre astronomique de clés uniques, ce qui signifie qu'il est presque impossible de deviner une clé d'API.

Pour générer une clé API pour un utilisateur donné, les utilisateurs doivent se connecter et cliquer sur leur nom dans le coin supérieur droit de n’importe quelle page pour accéder au menu contextuel de l’utilisateur. Il y aura une option "API Keys" dans ce menu pour aller à la page.

Si une clé d'API inconnue est utilisée à plusieurs reprises, l'API désactivera l'accès pendant un certain temps. Les utilisateurs pourront toujours se connecter au site Web du Command Center pendant cette période. Lorsque l'API est désactivée, elle renvoie une réponse HTTP 403 Forbidden à toutes les demandes reçues.

Au niveau HTTP, la clé d'API est envoyée via l'authentification de base HTTP. Utilisez la clé secrète comme nom d'utilisateur et toute chaîne aléatoire pour le mot de passe.

Pour plus d'informations sur l'authentification HTTP de base, voir cet article utile de wikipedia .

Faire des demandes

• Toutes les demandes adressées à nos API doivent être envoyées via HTTPS. Le certificat SSL utilisé pour la connexion HTTPS est signé et toutes les implémentations doivent configurer leur couche SSL pour le vérifier.
• les demandes sont adressées à une URL commençant par: https://api.baseline.info/
• Les demandes d'API peuvent être limitées si Baseline les juge trop fréquentes. Les implémentations doivent toujours être prêtes pour une réponse Service non disponible 503.
• Les implémentations doivent également toujours être prêtes à la perte de paquets Internet générale, entraînant des connexions interrompues sans réponse HTTP.
• Chaque employé a un identifiant d'employé immuable unique dans une seule entreprise que vous pouvez utiliser pour référencer l'employé.
• Toutes les demandes doivent être en UTF-8.

Codes d'état HTTP

Chaque demande inclut un code de statut HTTP avec le résultat. Le code d'état doit être examiné avant la réponse.

Codes d'état réussis (2xx)

• 200 OK - La demande a abouti.
• 201 Created - La ressource a été créée avec succès. Confirme le succès lors de la création d'un nouvel employé, d'une demande de congé, etc.

Codes d'état d'erreur client (4xx)

• 400 Requête incorrecte - La requête n'était pas valide ou ne pouvait pas être comprise par le serveur. Soumettre à nouveau la demande entraînera probablement la même erreur.
• 401 Unauthorized - Votre clé API est manquante.
• 403 Interdit - L'application tente d'exécuter une action à laquelle elle ne dispose pas de privilèges d'accès. Vérifiez que votre clé d'API appartient à un utilisateur activé avec les autorisations requises.
• 404 Introuvable - La ressource n'a pas été trouvée avec l'identifiant donné. L'URL indiquée n'est pas une API valide ou l'ID de l'objet spécifié dans la demande n'est pas valide.
• 406 Non acceptable - La demande contient des références à des champs inexistants.
• 409 Conflit - La demande tente de créer un doublon. Pour les employés, les courriels en double ne sont pas autorisés. Pour les listes, les doublons ne sont pas autorisés.
• 429 Limite dépassée - Le compte a atteint sa limite d'employés. Aucun employé supplémentaire ne peut être ajouté.

Codes d'état d'erreur du serveur (5xx)

• 500 Internal Server Error - Le serveur a rencontré une erreur lors du traitement de votre demande et a échoué.
• 502 Erreur de passerelle - L'équilibreur de charge ou le serveur Web a eu des problèmes de connexion à l'application Command Center. S'il-vous-plait essayez la demande une nouvelle fois.
• 503 Service indisponible - Le service est temporairement indisponible. S'il-vous-plait essayez la demande une nouvelle fois.

Vous pouvez tester votre code pour l'avenir en utilisant les plages suivantes:

• 200-299 comme succès
• 400 à 499 en tant qu'erreurs de demande client
• 500 à 599 en tant qu'erreurs de serveur

Compatibilité entre les versions

Tout sera mis en œuvre pour n'apporter que des modifications compatibles avec la transmission à l'API. Pour faciliter cet effort, les utilisateurs d’API doivent ignorer les balises et attributs XML qu’ils ne reconnaissent pas.

L'API prendra en charge plusieurs numéros de version majeurs de l'API. Actuellement, la seule version est "v1". Si une modification majeure de l'API devient nécessaire, nous allons créer un nouveau numéro de version majeure et communiquer la modification à nos partenaires. Nous allons maintenir l'API "v1" existante pendant une période de temps raisonnable.

Compatibility Between Versions

Every attempt will be made to make only forward compatible changes to the API. To assist this effort, API consumers should ignore any XML tags and attributes they do not recognize.

The API will support multiple major version numbers of the API. Currently the only version is "v1". If a major API change becomes necessary, we’ll create a new major version number and communicate the change to our partners. We’ll maintain the existing "v1" API for a reasonable period of time.