Une API, ou interface de programme d'application, est un ensemble de règles qui définit comment les applications ou appareils se connectent les uns aux autres et communiquent. Une API REST est une API qui respecte les principes de conception de REST, ou le style architectural de transfert d'état de représentation.  Pour cette raison, les API REST sont parfois appelées API RESTful.

Défini pour la première fois en 2000 par l'informaticien, le docteur Roy Fielding dans sa thèse de doctorat, REST fournit un niveau relativement élevé de flexibilité et de liberté pour les développeurs. Cette flexibilité n'est qu'une des raisons pour lesquelles les API REST ont émergé en tant que méthode commune de connexion de composants et d'applications dans une architecture de microservices.

Au niveau le plus basique, une API est un mécanisme permettant à une application ou à un service d'accéder à une autre application ou service. L'application ou le service qui effectue l'accès s'appelle le client et l'application ou le service qui contient la ressource s'appelle le serveur.

Certaines API, telles que SOAP ou XML-RPC, imposent un cadre strict aux développeurs. Mais les API REST peuvent être développées à l'aide de pratiquement n'importe quel langage de programmation et prennent en charge divers formats de données. La seule exigence qui leur est liée est qu'elles respectent les six principes de conception REST suivants, également appelés contraintes architecturales :

1. Interface uniforme. Toutes les demandes d'API d'une même ressource doivent avoir la même apparence, quelle que soit l'origine de la demande. L'API REST doit garantir que le même élément de données, tel que le nom ou l'adresse électronique d'un utilisateur, n'appartient qu'à un seul identificateur URI (Uniform Resource Identifier). Les ressources ne doivent pas être trop volumineuses, mais elles doivent contenir toutes les informations dont le client peut avoir besoin.
   
   
2. Découplage client-serveur. Dans la conception d'API REST, les applications client et serveur doivent être totalement indépendantes les unes des autres. Les seules informations que l'application client doit connaître sont l' URI de la ressource demandée ; elle ne peut pas interagir avec l'application serveur d'une autre manière. De même, une application serveur ne doit pas modifier l'application client autrement qu'en lui transmettant les données demandées via HTTP.
   
   
3. Sans état. Les API REST sont sans état, ce qui signifie que chaque demande doit inclure toutes les informations nécessaires à son traitement. En d'autres termes, les API REST ne nécessitent aucune session côté serveur. Les applications serveur ne sont pas autorisées à stocker des données liées à une demande client.
   
   
4. Mise en cache. Dans la mesure du possible, les ressources doivent pouvoir être mises en cache du côté client ou du côté serveur. Les réponses du serveur doivent également contenir des informations indiquant si la mise en cache est autorisée pour la ressource distribuée. L'objectif est d'améliorer les performances côté client tout en augmentant l'évolutivité du serveur.
   
   
5. Architecture système en couches. Dans les API REST, les appels et les réponses passent par différentes couches. En règle générale, ne supposez pas que les applications client et serveur se connectent directement l'une à l'autre. Il peut exister un certain nombre d'intermédiaires différents dans la boucle de communication. Les API REST doivent être conçues de manière à ce que ni le client ni le serveur ne puissent savoir s'ils communiquent avec l'application finale ou avec un intermédiaire.
   
   
6. Code à la demande (facultatif). Les API REST envoient généralement des ressources statiques, mais dans certains cas, les réponses peuvent également contenir du code exécutable (par exemple, des applets Java). Dans ce cas, le code ne doit être exécuté qu'à la demande.

Les API REST communiquent via des requêtes HTTP pour exécuter des fonctions de base de données standard telles que la création, la lecture, la mise à jour et la suppression d'enregistrements (également appelées CRUD) dans une ressource. Par exemple, une API REST utilise une requête GET pour récupérer un enregistrement, une requête POST pour en créer un, une requête PUT pour mettre à jour un enregistrement et une requête DELETE pour en supprimer un. Toutes les méthodes HTTP peuvent être utilisées dans les appels d'API. Une API REST bien conçue est similaire à un site Web exécuté dans un navigateur Web avec une fonctionnalité HTTP intégrée.

L'état d'une ressource à un instant ou un horodatage donné s'appelle la représentation de la ressource. Ces informations peuvent être fournies à un client dans pratiquement n'importe quel format, y compris JavaScript Object Notation (JSON), HTML, XLT, Python, PHP ou un texte en clair. JSON est communément utilisé, car il est lisible à la fois par l'utilisateur et les machines, et il est indépendant du langage de programmation.

Les en-têtes de demande et les paramètres sont également importants dans les appels d'API REST, car ils contiennent des informations d'identification importantes telles que les métadonnées, les autorisations, les identificateurs URI (Uniform Resource Identifier), la mise en cache, les cookies, etc. Les en-têtes de requête et les en-têtes de réponse, ainsi que les codes d'état HTTP conventionnels, sont utilisés dans les API REST bien conçues.

Bien que la flexibilité soit le grand avantage de la conception des API REST, cette même flexibilité facilite la conception d'une API endommagée ou peu performante. Pour cette raison, les développeurs professionnels partagent les meilleures pratiques dans les spécifications d'API REST.

La OpenAPI Specification (OAS) établit une interface pour décrire une API d'une manière permettant à un développeur ou application de la découvrir et de comprendre totalement ses paramètres et fonctionnalités : les points de terminaison disponibles, les opérations autorisées sur chaque point de terminaison, les paramètres opérationnels, les méthodes d'authentification et d'autres informations. La version la plus récent récente, OAS3 (lien externe à ibm.com), comprend des outils, tels qu'OpenAPI Generator, pour générer des clients d'API et des stubs de serveur dans différents langages de programmation.

La sécurisation d'une API REST commence également par les meilleures pratiques du secteur, comme l'utilisation d'algorithmes de hachage pour la sécurité des mots de passe et du protocole HTTPS pour la transmission sécurisée des données. Une structure d'autorisation telle que OAuth 2.0 (lien externe à ibm.com) peut permettre de limiter les privilèges des applications tiers. En utilisant un horodatage dans l'en-tête HTTP, une API peut également rejeter toute demande qui arrive après un certain délai. La validation des paramètres et les jetons Web JSON sont d'autres moyens de garantir que seuls les clients autorisés peuvent accéder à l'API.