Une API permet à un logiciel de communiquer à un autre.
La programmation d'une API va consister à définir comment un logiciel peut contrôler les fonctionnalités qu'elles exposent et les interactions possibles ( création, mise à jour ou suppression de données) de manière sécurisée aux autres logiciels ou à un utilisateur.
Voici quelques-uns cas d'utilisation pour les API:
Les API sont généralement conçues pour être synchrones lorsque les données de la requête sont facilement disponibles, par exemple lorsque les données sont stockées dans une base de données ou dans une mémoire interne. Le serveur peut immédiatement récupérer ces données et répondre immédiatement.
L'application cliente qui effectue la demande d'API doit attendre la réponse avant d'effectuer des tâches supplémentaires d'exécution de code.
Avantages : l'application reçoit les données immédiatement. Inconvénient : si l'API n'est pas correctement conçue, elle sera un goulot d'étranglement car l'application doit attendre la réponse.
Si la requête d'API prend un certain temps de traitement pour le serveur ou si les données ne sont pas facilement disponibles, il est préférable d'utiliser des API asynchrones.
L'application cliente doit alors être en mesure d'être informer ou de s'informer lorsque le résultat de sa requête API est disponible.
Avantages : l'application client peut de poursuivre l'exécution sans être bloquée pendant le temps nécessaire au serveur pour traiter la demande. L'application client peut avoir de meilleures performances car elle peut être multitâche et faire d'autres requêtes. Inconvénient : l'utilisation inutile ou excessive d'appels asynchrones peut avoir l'effet inverse sur les performances.
Les trois types les plus populaires de styles architecturaux API sont RPC, SOAP et REST.
REST ou REprésententational State Transfer (REST) est un style architectural rédigé par l'informaticien américain Roy Thomas Fielding au chapitre 5 de sa thèse de doctorat, Architectural Styles and the Design of Networkbased Software Architectures, en 2000.
Roy Thomas Fielding définit six contraintes appliquées aux éléments de l'architecture:
Quand ces six contraintes sont appliquées il s'agit d'une API RESTful.
Une API de service Web REST (REST API) est une interface de programmation (API) qui communique via HTTP tout en respectant les principes du style architectural REST.
Comme une API REST communique via HTTP, elle utilise les mêmes concepts que le protocole HTTP :
Les requêtes d'API REST sont composées de quatre composants principaux:
Les méthodes HTTP :
Méthode | HTTP | Action | Description |
---|---|---|---|
POST | Créer | Créez un nouvel objet ou une nouvelle ressource. | |
GET | Lecture | Récupérez les détails des ressources à partir du système. | |
PUT | Mettre à jour | ||
PATCH | Mise à jour partielle | Mettez à jour certains détails à partir d'une ressource existante. | |
DELETE | Supprimer | une ressource du système. |
Exemple d'en-tête de requête fournissant le jeton d'accès d'identification :
Clé | Exemple de valeur | Description |
---|---|---|
Autorisation | dmFncmFudDp2YWdyYW50 | Fournir des informations d'identification pour autoriser la demande |
Les en-têtes d'entité sont des informations supplémentaires qui décrivent le contenu du corps du message.
Exemple d'en-tête d'entité précisant le format des données souhaité :
Clé | Exemple de valeur | Description |
---|---|---|
Type de contenu | application/json | Spécifier le format des données dans le corps |
Les réponses API REST sont similaires aux requêtes, mais sont composées de trois composants principaux:
Les cinq catégories de réponse d'API REST :
Les codes d'état HTTP communs :
Code d'état HTTP | Messages d'état | Description |
---|---|---|
200 | OK | La requête a réussi et contient généralement une charge utile (corps) |
201 | Créé | La demande a été exécutée et la ressource demandée a été créée |
202 | Accepté | La demande a été acceptée pour traitement et est en cours |
400 | Demande incorrecte | La demande ne sera pas traitée en raison d'une erreur avec la demande |
401 | Non autorisé | La requête n'a pas d'informations d'identification d'authentification valides pour effectuer la demande |
403 | Interdit | La demande a été comprise mais a été rejetée par le serveur |
404 | Introuvable | Impossible d'exécuter la demande car le chemin de ressource de la demande n'a pas été trouvé sur le serveur |
500 | Erreur interne du serveur | La demande ne peut pas être traitée en raison d'une erreur de serveur |
503 | Service non disponible | La demande ne peut pas être traitée car actuellement le serveur ne peut pas gérer la demande |
L'interaction avec un service d'API REST particulier consiste en une séquence de demandes. Pour cette raison, les diagrammes de séquence sont fréquemment utilisés pour expliquer la requête/réponse de l'API REST et l'activité asynchrone.
Pour des raisons de sécurité, la plupart des API REST nécessitent une authentification afin que les utilisateurs aléatoires ne puissent pas créer, mettre à jour ou supprimer des informations de manière incorrecte ou malveillante, ou accéder à des informations qui ne devraient pas être publiques. La nécessité d'une authentification est le même concept que l'exigence d'un nom d'utilisateur/mot de passe pour accéder à la page d'administration d'une application.
Des API qui ne nécessitent pas d'authentification sont généralement en lecture seule et ne contiennent pas d'informations critiques ou confidentielles.
L'authentification permet de prouver l’identité du client.
L'autorisation définit l’accès du client à des données.
Les types courants de mécanismes d'authentification incluent Basic, Bearer et API Key.
Cette authentification utilise le schéma d'authentification HTTP de base standard en transmettant les informations d'identification sous forme de paires nom d'utilisateur/mot de passe séparées par un deux-points ( : ) et encodées à l'aide de Base64.
C'est le mécanisme d'authentification le plus simple mais est extrêmement peu sécurisé à moins qu'il ne soit jumelé avec des requêtes utilisant HTTPS plutôt que HTTP. Bien que les informations d'identification soient encodées, elles ne sont pas chiffrées. Il est simple de décoder les informations d'identification et d'obtenir la paire nom d'utilisateur/mot de passe.
Dans une requête d'API REST, les informations d'authentification de base seront fournies dans l'en-tête:
Authorization: Basic <username>:<password>
Ce mécanisme d'authentification appelé aussi authentification au jeton, utilise le schéma d'authentification HTTP au porteur standard. Il est plus sécurisé que l'authentification de base et est généralement utilisé avec OAuth et Single Sign-On (SSO). L'authentification au porteur utilise un jeton porteur, qui est une chaîne générée par un serveur d'authentification externe tel qu'un service d'identité (ID).
Tout comme l'authentification de base, l'authentification au porteur doit être utilisée avec HTTPS.
Dans une requête d'API REST, les informations d'authentification du porteur seront fournies dans l'en-tête :
Authorization: Bearer <bearer token>
Une clé API ou jeton API, est une chaîne alphanumérique unique générée par le serveur et affectée à un utilisateur. Pour obtenir une clé API unique, l'utilisateur se connecte généralement à un portail à l'aide de ses informations d'identification. Cette clé est généralement assignée une fois et ne sera pas régénérée. Toutes les requêtes d'API REST pour cet utilisateur doivent fournir la clé d'API assignée comme forme d'authentification.
Tout comme avec les autres types d'authentification, les clés API ne sont sécurisées que lorsqu'elles sont utilisées avec HTTPS.
Les clés API sont destinées à être un mécanisme d'authentification, mais sont généralement utilisées à mauvais escient comme mécanisme d'autorisation.
Les deux types de clés API sont publiques et privées.
La plupart des clés d'API n'expirent pas, et à moins que la clé ne puisse être révoquée ou régénérée, si elle est distribuée ou compromise, toute personne disposant de cette clé peut accéder indéfiniment au système comme vous.
Une requête API REST peut fournir une clé API de différentes manières:
Query string: Recommandé uniquement pour les clés API publiques
Authorization: <API Key> ou Authorization: APIkey <API Key> ou APIkey: <API Key>
Content-Type: application/json
Cookie: API_KEY=<API Key>