WordPress: Ajout de points de terminaison par lots ou en bloc à votre API REST

WordPress: Ajout de points de terminaison par lots ou en bloc à votre API REST

Il y a près de deux décennies, l’idée d’une API REST a été conceptualisée par Roy Fielding. L’idée est rapidement devenue très populaire. Par rapport aux méthodes existantes, telles que SOAP et RPC, qui permettaient aux utilisateurs d’interagir par programmation avec des applications sur Internet, REST a fourni un modèle bien structuré et facile à raisonner, et pourrait être implémenté pour résoudre un large variété de besoins. Semblable à la programmation orientée objet (OOP) et aux bases de données relationnelles, REST a permis aux programmeurs de penser à un ensemble connecté de Ressources — similaire aux objets de la POO ou des tables de base de données — qui pourraient être modifiés à l’aide d’un ensemble limité de HTTP standard verbes, qui pourrait être considéré comme un parallèle aux méthodes des opérations OOP ou CRUD (Créer, Lire, Mettre à jour, Supprimer) dans les bases de données.

La conception orientée ressources des API REST est plus populaire que jamais aujourd’hui, mais il existe des limites et des points où il est facile de trébucher. Dans cet article, nous allons examiner spécifiquement l’idée de grouper ou masse opérations sur une API REST, pourquoi elles sont généralement nécessaires, et comparez les différentes manières de les implémenter.

Il convient de noter que certaines personnes, comme Jean Apostolidis, font une nette distinction entre masse traitement (application de la même opération à plusieurs entrées) et grouper traitement (application d’opérations potentiellement différentes à différentes entrées). Bien qu’il soit logique d’avoir cette distinction, en réalité, les deux idées sont souvent confondues et utilisées de manière interchangeable. « Lot » est souvent considéré comme le terme plus général (traitement de lots de demandes ou lots de données) et « en vrac » en tant que sous-ensemble de lots (données de lots, mais pas d’opérations).

Pour ce tutoriel, vous devez déjà connaître au moins les bases de la conception d’API REST car nous ne l’expliquerons pas en détail. Nous nous concentrerons sur les raisons pour lesquelles les points de terminaison par lots peuvent être utiles et sur différentes manières de les ajouter à votre API REST existante.

Regarder un exemple d’API REST de jouet

Imaginons une API REST très simple qui est un sous-ensemble de l’API de traitement des paiements de Stripe. Nous ne considérerons que le point de terminaison /customers, qui est utilisé pour récupérer les clients existants ou en créer de nouveaux. La documentation nous informe que les options suivantes sont disponibles.

  POST 	/v1/customers
   GET 	/v1/customers/:id
  POST 	/v1/customers/:id
DELETE 	/v1/customers/:id
   GET 	/v1/customers

Nous pouvons immédiatement voir l’un des principaux avantages d’une API REST. Si vous avez déjà utilisé une API REST, même sans la documentation spécifique à Stripe, vous auriez probablement pu les deviner.

Pour créer un client, nous faisons une requête POST au /v1/customers et pour récupérer les clients, nous utilisons le même point de terminaison mais utilisons à la place une requête GET.

Pour récupérer, modifier ou supprimer un client existant, nous utilisons toujours le /customers point final, mais nous ajoutons le :id du client spécifique qui nous intéresse en même temps.

Un détail légèrement contre-intuitif est la réflexion sur singulier et pluriel. Le point de terminaison s’appelle « /clients« , et appeler GET dessus renvoie effectivement de nombreux clients sous la forme d’un ensemble de dictionnaires (par ex. [{customer1...}, {customer2...}]). Cependant, à créer clients, nous AFFICHONS un seul client (par ex. {customer1...}. C’est le genre de détail que vous aurez probablement besoin de rechercher dans différentes API REST, car il n’est pas toujours implémenté de manière cohérente.

Pourquoi aurions-nous besoin de points de terminaison par lots ?

D’après les exemples ci-dessus, nous pouvons voir une asymétrie lorsque nous avons affaire à plusieurs clients en même temps. Si nous voulons récupérer les informations de tous nos clients à la fois, nous pouvons simplement appeler GET /v1/customers et nous aurons toutes les données dont nous avons besoin. Si nous avons un ensemble existant de milliers de clients stockés en dehors de Stripe et que nous souhaitons ajouter chacun d’eux à Stripe, nous devrons les créer un par un, en appelant un seul POST /v1/customers pour chacun.

Le réseautage, ou plus précisément, le numéro d’appels que nous devons passer, est souvent le goulot d’étranglement dans les applications modernes. L’adoption de clouds publics tels qu’AWS a facilité l’augmentation de la puissance de traitement, de la RAM ou du stockage de nos applications, mais chaque appel réseau doit toujours négocier un réseau mondial compliqué et peu fiable d’ordinateurs, de routeurs, de commutateurs et de protocoles, comme TCP, ajoutant beaucoup de temps système pour chaque appel. Par conséquent, il est généralement préférable de faire moins de demandes avec plus de données (par exemple, plusieurs clients) plutôt que de faire plus de demandes avec moins de données (par exemple, un client) dans chaque demande.

Imaginez si nous avions créé l’API client simple illustrée ci-dessus et que nous voulions maintenant permettre aux utilisateurs de l’API de créer plusieurs clients à la fois. Comment ferions-nous cela? On pourrait simplement modifier POST /customers accepter un ensemble de clients au lieu d’un seul client. Faire cela correspondrait à ce que GET /customers le point de terminaison renvoie. Cependant, ce serait un changement radical pour notre API et ennuyeux pour les utilisateurs qui ne souhaitent ajouter qu’un seul client à chaque fois. Ils devraient toujours se souvenir d’ajouter le client ou le tableau avant de l’envoyer et de traiter un tableau renvoyé d’ID créés. Il est probable que, dans la majorité des cas, nos utilisateurs souhaitent ajouter un seul utilisateur à la fois.

Stripe n’implémente pas un moyen de créer plusieurs clients à la fois, mais examinons d’autres API qui ont un moyen de traiter les demandes par lots et voyons comment elles les traitent.

Examiner des exemples concrets d’API par lots

Lorsque vous rencontrez un problème de conception que vous n’êtes pas sûr de savoir comment le résoudre, la meilleure première étape consiste souvent à examiner comment d’autres ont résolu le problème. Heureusement, les API REST avec une documentation publique ne manquent pas. La plupart des API choisissent soit
implémentez un point de terminaison qui peut regrouper différentes demandes en un seul appel, ou une version en bloc de certains (ou de tous) des points de terminaison qui peuvent accepter plusieurs ressources en un seul appel.

Nous commencerons par regarder Google Drive, un exemple de la première option, avant de regarder ZenDesk, un exemple de cette dernière option.

Google Drive – requêtes par lots

Google Drive est surtout connu pour être un service de stockage en nuage, similaire à Dropbox, mais il comprend également une puissante API pour créer, modifier et récupérer des documents de toutes sortes.

Google a mis en place un point de terminaison de lot compliqué mais flexible. Au lieu d’avoir un point de terminaison qui accepte plusieurs Ressources, il existe un point de terminaison qui accepte plusieurs demandes. Ce sont essentiellement des « méta » requêtes HTTP, où la requête principale contient différentes sous-requêtes.

L’avantage de cette approche est qu’elle est très flexible. Google peut accepter différents types de requêtes POST, chacune contenant des données différentes, dans un seul appel réseau, et les traiter en parallèle côté serveur, réduisant ainsi le nombre d’appels réseau que leurs proxys API doivent gérer.

Le principal inconvénient de cette approche est qu’il est assez difficile de créer des requêtes POST qui ressemblent à ceci. Il est assez facile pour les utilisateurs de manipuler les données qu’ils transmettent avec une requête (par exemple pour commencer à utiliser un tableau de clients s’ils savent déjà comment passer par un seul client), mais c’est beaucoup plus compliqué pour les utilisateurs de regrouper différentes API demandes ensemble et les envoyer à un nouveau point de terminaison. Même dans le cas où les wrappers d’API sont fournis dans un langage de haut niveau, les utilisateurs doivent toujours réfléchir davantage au moment où il est judicieux de regrouper différentes demandes, à la meilleure façon de les combiner et à la manière dont les demandes interagiraient les unes avec les autres.

Dans l’exemple de Google, comme copié ci-dessous, nous avons envoyé une requête POST par lot qui contient deux sous-requêtes POST. Chacune des requêtes POST internes crée des autorisations sur un fichier spécifique : la première donne une adresse e-mail spécifique à écrivez un fichier spécifique, et le second donne la permission à un domaine entier de lire un fichier spécifique.

Pour chaque requête embarquée, il existe un --END_OF_PART marqueur. Notez qu’il y a une certaine répétition, par exemple, le Authorization et Content-Type les champs sont répétés pour chaque sous-requête, même s’il est peu probable qu’ils soient différents. Une fois que cette demande de lot en plusieurs parties plus importante est livrée à Google, leurs serveurs la sépareront simplement et traiteront chaque section comme si elle était arrivée individuellement.

POST https://www.googleapis.com/batch/drive/v3
Accept-Encoding: gzip
User-Agent: Google-HTTP-Java-Client/1.20.0 (gzip)
Content-Type: multipart/mixed; boundary=END_OF_PART
Content-Length: 963


--END_OF_PART
Content-Length: 337
Content-Type: application/http
content-id: 1
content-transfer-encoding: binary



POST https://www.googleapis.com/drive/v3/files/fileId/permissions?fields=id
Authorization: Bearer authorization_token
Content-Length: 70
Content-Type: application/json; charset=UTF-8



{
  "emailAddress":"example@appsrocks.com",
  "role":"writer",
  "type":"user"
}
--END_OF_PART
Content-Length: 353
Content-Type: application/http
content-id: 2
content-transfer-encoding: binary



POST https://www.googleapis.com/drive/v3/files/fileId/permissions?fields=id&sendNotificationEmail=false
Authorization: Bearer authorization_token
Content-Length: 58
Content-Type: application/json; charset=UTF-8



{
   "domain":"appsrocks.com",
   "role":"reader",
   "type":"domain"
}
--END_OF_PART--

ZenDesk – ressources par lots

ZenDesk est un système de support client et de billetterie. Ils ont adopté une approche légèrement différente pour la mise en œuvre des API par lots. Vous pouvez lire leur article de blog expliquant pourquoi ils ont ajouté des points de terminaison par lots et consulter leur documentation API pour voir exactement comment fonctionne la mise en œuvre.

Semblable à l’API Google Drive que nous avons examinée précédemment, ZenDesk a un point de terminaison différent pour gérer les demandes par lots, mais contrairement à Google, il existe un point de terminaison de lot par type de ressource au lieu d’un seul point de terminaison de lot pour toutes les ressources. Par exemple, vous utiliseriez le point de terminaison suivant pour créer de nombreux utilisateurs :

POST /api/v2/users/create_or_update_many.json

Tu verras ça users est toujours inclus dans le point de terminaison ci-dessus, par opposition à Google Drive, où nous devions spécifier chaque point de terminaison que nous voulions dans les données des sous-sections de la requête POST. L’exemple qu’ils ont utilisé pour montrer comment passer par plusieurs utilisateurs à la fois est comme prévu : nous créons un tableau d’utilisateurs, en spécifiant les informations pour chacun. Notez que l’exemple de la documentation ZenDesk suppose que vous utilisez l’une de leurs bibliothèques API, au lieu de créer la requête POST brute, il semble donc un peu plus soigné que l’exemple de Google. Les données JSON finiraient toujours par être encodées dans le corps du POST, et le Content-Length, Content-Type, et d’autres en-têtes seraient ajoutés avant l’envoi.

'{"users": [{"name": "Roger Wilco", "email": "roge@example.org", "role": "agent"}, {"external_id": "account_54321", "name": "Woger Rilco", "email": "woge@example.org", "role": "admin"}]}'

L’avantage de cette approche est qu’elle est simple à utiliser. Si les utilisateurs de notre API savent comment créer une seule ressource et rencontrent des problèmes de performances dus à la nécessité de créer plusieurs ressources à la fois, ils peuvent facilement modifier leur code existant pour passer par un tableau, au lieu d’une seule ressource.

L’inconvénient est qu’il est moins flexible que le point de terminaison de lot générique. Si nous voulons créer plusieurs utilisateurs, organisations et tickets en même temps, nous devrons tout de même passer au moins trois appels réseau. Alors qu’avec la conception de Google, nous n’aurions besoin de faire qu’une seule demande par lot en regroupant ces différents points de terminaison.

Trouver d’autres approches

Nous n’avons examiné que deux exemples, mais vous verrez les deux modèles utilisés par plusieurs entreprises. Il est assez facile de trouver plus d’exemples en recherchant sur Internet « Documentation API » suivi d’un mot-clé d’une grande entreprise technologique. Vous remarquerez une large gamme de qualité dans la documentation de l’API. Stripe, par exemple, est bien connu pour investir beaucoup de temps et d’argent pour s’assurer que sa documentation API est bien conçue, précise et facile à utiliser. Les entreprises plus anciennes et plus corporatives, telles que Salesforce et Oracle, ont généralement une documentation moins complète et plus difficile à interpréter.

Il est intéressant de voir comment différents endroits implémentent les requêtes en masse et par lots de manière légèrement différente (voire pas du tout). Il est également intéressant de noter que bon nombre des points de terminaison en vrac ou par lots qui existent sont étiquetés comme « expérimentaux » ou ont été ajoutés à un stade beaucoup plus tardif que les points de terminaison principaux. De toute évidence, le traitement par lots et en masse n’est pas quelque chose qui s’intègre naturellement dans les principes de conception de base des API REST ou orientées ressources. Cela dit, c’est un sujet suffisamment compliqué pour qu’il vaut la peine de réfléchir aux différentes options avant d’ajouter aveuglément des points de terminaison à votre API au moment où vous réalisez que vous en avez besoin.

Autres considérations pour le traitement par lots

Nous avons examiné quelques exemples de traitement d’API par lots et fait une distinction entre grouper et masse extrémités. Outre les problèmes que nous avons mentionnés, vous devrez également en tenir compte lors de la mise en œuvre de points de terminaison par lots ou en bloc :

  • Gestion des erreurs : que se passe-t-il si une seule demande ou ressource dans une demande par lots échoue ? L’ensemble du lot doit-il échouer ou doit-il traiter autant de demandes que possible ?
  • Limitation de la taille des lots : de nombreux points de terminaison spécifient un limite de taux du nombre de fois que chaque point de terminaison peut être appelé dans une fenêtre de temps spécifique. Si vous ajoutez des points de terminaison par lots, vos utilisateurs peuvent envoyer d’énormes quantités de données à traiter et il peut être difficile de les suivre.
    Il ressort clairement des exemples ci-dessus que le traitement par lots et en masse est souvent ajouté aux API REST après coup, lorsque des goulots d’étranglement réseau sont découverts.

Que vous commenciez tout juste la conception de votre API ou que vous ayez identifié le besoin de traitement par lots après l’adaptation à de vrais utilisateurs, il est bon de comprendre les différentes façons dont le traitement par lots dans les API REST peut être mis en œuvre, ainsi que les avantages et les inconvénients à jouer.

.

All the CMS Templates You Could Ask For.

WordPress: Ajout de points de terminaison par lots ou en bloc à votre API REST

2M+ items from the worlds largest marketplace for CMS Templates, Themes & Design Assets. Whether that's what you need, or you're just after a few Stock Photos - all of it can be found here at Envato Market.



WordPress: Ajout de points de terminaison par lots ou en bloc à votre API REST

#Ajout #points #terminaison #par #lots #bloc #votre #API #REST