Comprendre et utiliser les API RESTful

À l'ère de l'Internet des Objets, il existe de nombreuses API différentes, et il est important de les standardiser. L'API RESTful est l'un des styles d'architecture d'API les plus populaires, qui peut vous aider à séparer les préoccupations côté client et côté serveur, permettant ainsi aux parties frontales et dorsales d'itérer séparément, améliorant ainsi l'efficacité. Sa caractéristique sans état peut rendre l'application plus évolutive et faciliter la mise en œuvre de politiques de mise en cache pour améliorer l'expérience utilisateur et les performances. Dans cet article, nous allons présenter ce qu'est une API RESTful et comment l'utiliser.

Qu'est-ce qu'une API

Laissons de côté ce qu'est une API pour un moment et parlons de la manière dont nous transmettons des informations dans notre vie quotidienne.

Lorsque vous donnez votre argent au propriétaire du magasin et lui dites que vous avez besoin d'acheter des piles, le propriétaire reçoit l'argent, trouve les piles sur l'étagère et vous les remet. Une transaction pour acheter une pile est ainsi réussie.

Les logiciels informatiques, quant à eux, accomplissent cela via des API. Commençons par la définition de Wikipédia :

Une interface de programmation d'application (API) est un moyen pour deux ou plusieurs programmes informatiques de communiquer entre eux. C'est un type d'interface logicielle, offrant un service à d'autres logiciels.

Le logiciel A fait une demande au logiciel B via l'API, et le logiciel B renvoie la réponse à A via l'API après avoir interrogé ses ressources.

Le logiciel A faisant une demande au logiciel B via l'API est comme vous disant à votre patron que vous avez besoin d'une pile, et le logiciel B renvoyant les données au logiciel A est comme votre patron trouvant la pile et vous la donnant.

Ce processus ne nécessite pas que le logiciel B sache pourquoi le logiciel A veut les données, tout comme un propriétaire de magasin ne vous demanderait pas pourquoi vous avez acheté la pile. Le logiciel A n'a pas non plus besoin de savoir comment le logiciel B a trouvé les données, tout comme vous ne demanderiez pas au propriétaire où les piles ont été achetées lorsque vous les achetez. Chaque logiciel transmet des informations à l'autre via des API, et chacun fait son propre travail, rendant le monde de la programmation ordonné et fiable.

Qu'est-ce qu'une API RESTful

Roy Fielding a défini REST (Transfert d'état représentatif) dans sa thèse de doctorat de 2000, "Architectural Styles and Web-Based Software Architecture Design", et le style architectural REST définit six contraintes directrices. Un système qui respecte certaines ou toutes ces contraintes est communément appelé RESTful.

(Source : Seobility)

Contraintes des API RESTful

Meilleures pratiques pour les API RESTful

L'accent mis sur les interfaces unifiées entre les composants est une caractéristique centrale qui distingue le style architectural REST des autres styles basés sur le web, et sur la base de cette caractéristique, les meilleures pratiques sont triées ici pour vous aider à mieux concevoir votre API.

Éviter les verbes dans le nom du chemin

Utilisez les méthodes HTTP pour exprimer le comportement de manipulation des ressources, au lieu de définir des verbes de comportement dans les chemins.

// Bon
curl -X GET http://httpbin.org/orders

// Mauvais
curl -X GET "http://httpbin.org/getOrders"

• Obtenez les informations de la ressource pour l'URI spécifiée en utilisant GET

// Représente l'obtention de toutes les informations de commande pour le système actuel
curl -X GET http://httpbin.org/orders

// Représente l'obtention des informations détaillées de la commande numéro 1
curl -X GET http://httpbin.org/orders/1

• Créez une ressource à partir de l'URI spécifiée en utilisant POST

 // Représente la création d'une ressource avec le nom order
curl -X POST http://httpbin.org/orders \
  -d '{"name": "awesome", region: "A"}' \

• Créez ou remplacez entièrement les ressources sur l'URI spécifiée en utilisant PUT

 // Représente le remplacement des données pour une commande avec l'id 1
curl -X PUT http://httpbin.org/orders/1 \
  -d '{"name": "new awesome", region: "B"}' \

• PATCH effectue une mise à jour partielle d'une ressource

 // Représente la modification du champ region de la commande avec l'id 1, tout en gardant le reste des données inchangées
curl -X PATCH http://httpbin.org/orders/1 \
  -d '{region: "B"}' \

• Supprimez une ressource en spécifiant une URI en utilisant DELETE

 // Représente la suppression de la commande avec l'id 1
curl -X DELETE http://httpbin.org/orders/1

Les URI utilisent la forme plurielle

Si vous souhaitez utiliser la forme singulière pour indiquer l'accès à un type particulier de ressource :

curl -X GET "http://httpbin.org/order"

L'utilisation de la forme singulière peut confondre l'utilisateur en lui faisant croire qu'il n'y a qu'une seule commande dans le système, mais l'utilisation de la forme plurielle rend la compréhension beaucoup plus fluide.

curl -X GET "http://httpbin.org/orders"

Bien utiliser les codes d'état HTTP

La norme HTTP définit des codes d'état, qui peuvent être classés en grandes catégories comme suit :

En utilisant des codes d'état standard, les développeurs peuvent immédiatement identifier les problèmes et réduire le temps nécessaire pour trouver différents types d'erreurs.

Gestion des versions

Comme les besoins métier évoluent, les API déjà en ligne devront très probablement être ajustées en conséquence. Si nos API sont utilisées par des tiers, il est évidemment impossible de demander à chaque client de changer en fonction des modifications de nos API, il est donc temps d'introduire le concept de gestion des versions d'API, qui peut garantir l'utilisation normale des API historiques et itérer de nouvelles API pour répondre aux nouveaux besoins métier.

Les moyens courants de gestion des versions sont :

• Gestion des versions via les chemins dans les demandes

// Demande de l'API v1
curl  http://httpbin.org/v1/orders

// Demande de l'API v2
curl  http://httpbin.org/v2/orders

• Gestion des versions via les paramètres de requête

// Demande de l'API v1
curl  http://httpbin.org/orders?version=v1

// Demande de l'API v2
curl  http://httpbin.org/v2/orders?version=v2

• Gestion des versions via l'en-tête

// Demande de l'API v1
curl  http://httpbin.org/orders -H "custom-version: v1"

// Demande de l'API v2
curl  http://httpbin.org/orders -H "custom-version: v2"

Comment APISIX renforce les API RESTful

Apache APISIX est une passerelle API dynamique, en temps réel et haute performance. Elle peut fonctionner devant tout service API RESTful et utiliser des plugins pour ajouter de nouveaux services et étendre ses fonctionnalités, ce qui est conforme à la définition RESTful de Système en couches. De plus, pour certains services historiques qui ne suivent pas la définition de l'API RESTful, APISIX peut également vous aider à convertir votre interface sans modifier le code métier d'origine afin que votre interface respecte la contrainte REST d'Interface uniforme, rendant votre API plus conforme à la spécification de l'API RESTful.

Système en couches : Supporte la séparation de la logique métier et de la logique de sécurité

Vous pouvez simplement vous concentrer sur la mise en œuvre de la logique métier, la logique de sécurité de l'interface peut être laissée aux plugins de classe Authentication d'APISIX, par exemple key-auth. APISIX supporte un grand nombre de plugins Authentication, prenons openid-connect par exemple, comme le montre la figure suivante :

Nous pouvons voir qu'en utilisant APISIX (Passerelle API) pour ajouter une couche de logique d'authentification devant notre serveur métier, cela peut servir à protéger les services en amont, et ce modèle architectural peut bien découpler votre logique métier de la logique de sécurité.

Système en couches : Support de plusieurs protocoles de répartition de charge

APISIX, en tant que passerelle API, peut être configurée entre le client et le serveur pour répondre à différents besoins de répartition de charge. Vous pouvez même personnaliser la logique de répartition de charge.

Les algorithmes de répartition de charge supportés sont :

• roundrobin : Répartition de charge en robin avec des poids.
• chash : Hachage cohérent.
• ewma : Choisit le nœud avec la latence minimale. Voir EWMA Chart pour plus de détails.
• least_conn : Choisit le nœud avec la valeur la plus basse de (active_conn + 1) / weight. Ici, une connexion active est une connexion utilisée par la demande et est similaire au concept dans Nginx.
• Répartiteur de charge personnalisé chargé via require("apisix.balancer.your_balancer")

Interface uniforme : Rendre les API historiques plus RESTful

Pour les API historiques qui existent depuis longtemps et ne suivent pas bien les directives de l'API RESTful, vous pouvez réencapsuler la nouvelle API via APISIX pour répondre à différents scénarios métier sans modifier la logique de l'API d'origine.

• Utilisez proxy-rewrite pour réécrire les demandes client

Comme mentionné ci-dessus, nous ne devrions pas avoir de verbes dans notre chemin.

Par exemple, si l'API historique a l'interface /getOrder, nous pouvons rediriger la demande API vers l'API historique via le plugin proxy-rewrite.

curl http://127.0.0.1:9080/apisix/admin/routes/1  -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
    "methods": ["GET"],
    "uri": "/orders",
    "plugins": {
        "proxy-rewrite": {
            "uri": "/getOrder",
            "scheme": "http",
        }
    },
    "upstream": {
        "type": "roundrobin",
        "nodes": {
            "127.0.0.1:80": 1
        }
    }
}'

Vous pouvez également utiliser le plugin pour les opérations de versioning d'API.

• Utilisez le plugin response-rewrite pour réécrire les réponses du serveur

Lorsque notre API historique a des codes d'état de réponse non standardisés, nous pouvons utiliser response-rewrite pour rediriger la réponse afin de modifier le code d'état de réponse.

curl http://127.0.0.1:9080/apisix/admin/routes/1  -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
    "methods": ["GET"],
    "uri": "/orders",
    "plugins": {
        "response-rewrite": {
            "status_code": 201,
            "body": "{\"code\":\"ok\",\"message\":\"new json body\"}",
            "vars":[
                [ "status","==",200 ]
            ]
        }
    },
    "upstream": {
        "type": "roundrobin",
        "nodes": {
            "127.0.0.1:80": 1
        }
    }
}'

L'exemple ci-dessus représente une demande pour modifier le statut de 200 à 201 dans l'API demandant le chemin /orders.

Puisque APISIX supporte des plugins très riches, j'attends avec impatience que vous exploriez plus de façons de jouer.

Résumé

Cet article présente ce qu'est une API, ce qu'est une API RESTful, et ses meilleures pratiques. De plus, cet article présente également comment séparer la logique métier et la logique de sécurité via APISIX, et comment utiliser APISIX pour rendre les services API historiques plus RESTful sans modifier le code métier d'origine. J'espère que cet article vous aidera à comprendre les API RESTful.