IntroductionL’API REST fournit une API de services Web pratique, puissante, simple pour interagir avec des applications mobiles, Web et avec des systèmes d'informations via une connexion Web. Cela vous offre une grande facilité d'intégration et de développement. URL de base de l'API : https://api.api-datastore.com/api/v1.0/
Tous les appels de l'API commencent par cette URL à laquelle s'ajoute le chemin vers l'action désirée.
L'API est accessible uniquement via le protocole Https et accepte les requêtes HTTP GET, POST, PUT ou DELETE. Les données envoyées en POST doivent respecter le format JSON. |
IntroductionThe REST API provides a practical, powerful and simple Web service API to interact with mobile and Web applications. Some of its advantages are very easy integration and development. Base API URL : https://api.api-datastore.com/api/v1.0/
All API calls start with this URL to which the path to the required action is added.
The API can only be accessed using the Https protocol and accepts HTTP GET, POST, PUT or DELETE requests. Data sent using POST must comply with JSON format. |
Bien débuterPour interroger l'API, afin de permettre aux utilisateurs d'applications d'accéder en toute sécurité aux données sans avoir à révéler un nom d'utilisateur et mot de passe, nous avons mis en place deux systèmes au choix en fonction de l'usage. Cas 1 : Utilisation d'une API Key (pour des appels côté serveur (BackEnd))
Pour chaque appel à l'API, une API Key doit être donnée en argument GET (voir section Authentification). Cette API Key est unique pour chaque compte client, elle représente l’utilisateur auprès de l’API.
Sécurité : Il est possible de paramétrer une white liste d'IP's autorisées afin de limiter les appels depuis ces IP's dédiées correspondant au serveur BackEnd exécutant les appels vers l'API. Cas 2 : Utilisation du protocole OAuth avec une authentification par token (pour des appels côté poste client (FrontEnd))Un token est une clé encryptée, générée par le serveur à une demande de login. Elle permet au serveur d'identifier la personne qui fait la demande, le client doit pour cela envoyer le token dans le header Authentification de la requête : Authorization: Bearer <token> Contrairement à une Api Key, le token périme (code http 401), il faut donc demander un nouveau token pour continuer à effectuer des appels. |
Getting off to a good startTo use the API and access data in a secure way, without requiring users to reveal their usernames and passwords, We have implemented two possible authentication procedures. Option 1: Using an API Key (for calls coming from a server (Backend))
For each call to the API, an API Key must be given as a GET argument (see Authentication section). This API Key is unique for each customer account, and represents the user making the call.
Security : A white list of authorized IPs can be configured to limit calls to these specific IPs corresponding to the backend server making the calls to the API Option 2: Using the OAuth protocol with an authentication token (for client side calls (Frontend))A token is an encrypted key, generated by the server when an authentication request is made. This token then allows the server to identify the person making the request, and must be sent by the client as a request header: "Authorization: Bearer <token>" Unlike an API Key, the token will expire (HTTP status 401), and therefore must be refreshed to continue making calls to the API. |
AuthentificationRécupérer son API KeyCommencez par créer un compte démo "Testez gratuitement" ou connectez-vous sur votre espace client "Connexion" si vous avez déjà un compte. Depuis votre espace client, allez dans l’onglet « Ressources », rubrique «Clé API» Cas 1: Utiliser l’API KeyPour utiliser l’API Key, il suffit de la rajouter dans les paramètres des requêtes envoyées sous le format : apikey={MonAPIKey}
Lors de la réception d’une demande, l’API vérifie la présence ainsi que la conformité de l’API Key
utilisée. En cas contraire, une réponse HTTP 401 adaptée est renvoyée :
Cas 2: Utiliser un tokenEtape 1: Demande de token qui se fait via un POST sur la route /token, avec en body l'objet { username: email, password: password }, il est donc nécessaire de connaître les identifiants du compte pour en récupérer un. Cette demande de token doit donc se faire côté backend pour ne pas laisser passer dans la trame réseau votre login/mot de passe. Etape 2: Pour toutes les requêtes côté frontend, vous devez préciser dans le paramètre d’authentification sur le header de la requête, le token comme valeur. |
AuthenticationRetrieving your API KeyStart by creating a "Free trial" demo account or login to your customer area using "Connection" if you already have an account. From your customer area, go to the “Resources” tab, “API Keys” section Cas 1: Using the API KeyTo use the API Key, all you need to do is to add it to the parameters in sent requests in the following format: apikey={MonAPIKey}
When it receives a request, the API checks for the presence and conformity of the API Key being used. If this check fails, a suitable HTTP 401 response is returned:
Cas 2: Using TokenStep 1: Requesting a token is done by making a POST request to the path /token, with a body in the format { username: email, password: password }. It is therefore necessary to know the login details of an account to generate one. Step 2: For all front-end requests, the token must be included as the value of the authentication header. |
Contrôles des appels APIVérification de la routeSi la route n’a pas la bonne syntaxe, on renvoie une réponse 404 et un message donnant de l’information sur le contrôleur incorrect. Vérification des paramètres obligatoiresSi un paramètre obligatoire est absent, la méthode renvoie une réponse 400 avec un message indiquant la syntaxe d’appel.
Exemple: "Message": "Syntaxe de la requête invalide, syntaxe correcte"
Gestion des ExceptionsDès qu'une exception est levée, on envoie une réponse avec un message d’erreur et un statut de requête http. STATUT DU RETOUR, LISTE DES CODES
Chaque appel à l'API donne lieu à une réponse retournant un code spécifique en fonction du résultat
obtenu. L'analyse de ce code vous permet de vous assurer que la requête a été traitée avec succès.
|
API call checksRoute checkIf the route has invalid syntax, a 404 response is returned along with a message giving information on the incorrect controller. Mandatory parameter checkIf a mandatory parameter is missing, the method returns a 400 response with a message indicating the call syntax.
Exemple: "Message": "Invalid request syntax, correct syntax"
Exception managementAs soon as an exception occurs, a response is returned with an error message and an http request status. RETURN STATUS, CODE LIST
Each API call results in a response returning a specific code to the result. Analyzing this code allows you to ensure that the request was successfully completed.
|
Répartition de la consommationAfin de pouvoir présenter une répartition de la consommation, l'API peut recevoir un paramètre supplémentaire optionnel : divisionkey={MaCleDeRepartition} . Le paramètre doit être une clé vous permettant d'identifier le consommateur du service. Il peut être au format STRING, INT, GUID, etc. |
Distribution of consumptionIn order to be able to present a distribution of consumption, the API can receive an optional additional parameter: divisionkey={MyDistributionKey}. The parameter must be a key allowing you to identify the consumer of the service. It can be in the format STRING, INT, GUID, etc. |