Documentation API Data Store du Groupe IDAIA

(IDAIA Group API Data Store documentation)

Introduction

L’API REST fournit une API de services Web pratique, puissante, simple pour intéragir 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.
Exemple : https://api.api-datastore.com/api/v1.0/Company/byId/{id}

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.

Introduction

The 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.
Exemple : https://api.api-datastore.com/api/v1.0/Company/byId/{id}

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ébuter

Pour 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.
Ce système est simple à mettre en place, mais ne doit être utilisé que pour des appels côté serveur (BackEnd) pour garantir sa sécurité et éviter toute usurpation d’identité.

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 start

To 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.
It’s easy to install but the API Key must be used for backend server calls to guarantee its security and prevent identity theft.

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.

Authentification

Récupérer son API Key

Commencez 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 Key

Pour 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 :
- Demande sans API Key : « Message : "L’autorisation a été refusée pour cette demande. " »
- API Key non valide : « Message : "Clé API n’est pas valide" »

Cas 2: Utiliser un token

Etape 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 connaitre 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.

Authentication

Retrieving your API Key

Start 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 Key

To 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:
- Request without an API Key: " Message: "Authorization failed for this request." "
- Invalid API Key: "Message: "Invalid API key" "

Cas 2: Using Token

Step 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 API

Vérification de la route

Si 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 obligatoires

Si 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 Exceptions

Dè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.
Tous les codes >= 400 indiquent que la requête n'a pas été traitée avec succès par nos serveurs.

  • 200: OK
  • 204: OK, mais pas de résultat
  • 400: Paramètre manquant, ou valeur incorrecte
  • 401: Authentification nécessaire (jeton non précisé ou invalide)
  • 403: Action non autorisée (crédits épuisés, URL non autorisée, etc)
  • 404: Page inaccessible (URL inconnue / impossible d'accéder à l'adresse)
  • 500: Erreur inconnue, contactez-nous

API call checks

Route check

If the route has invalid syntax, a 404 response is returned along with a message giving information on the incorrect controller.

Mandatory parameter check

If 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 management

As 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.
All the codes >= 400 indicate that the request processing on our servers

  • 200: OK
  • 204: OK, but no result
  • 400: Missing parameter, or incorrect value
  • 401: Authentication required (no token or invalid token)
  • 403: Unauthorized action (no more credits, unauthorized URL, etc.)
  • 404: Page unavailable (Unknown URL / impossible to access the address)
  • 500: Unknown error, contact us

Répartition de la consommation

Afin 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 consumption

In 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.