💔 ✊🏽 🤶🏿 Recommandations de l'API REST - Exemples de conception de services Web dans Java et Spring 🏰 🕋 🌗

Dans le dernier article de cette série, vous découvrirez les recommandations de l'API REST et les exemples de développement des services Web Java et Spring.

Lors du développement d'une bonne API REST, il est important d'avoir de bons microservices.
Comment développez-vous votre API REST? Quelles sont les meilleures pratiques?

Vous apprendrez:

Comment développer une bonne API REST?
À quoi dois-je penser lors du développement d'une API REST?
Quelles sont les meilleures pratiques pour développer des services Web RESTful?

API REST

Voici le dernier article d'une série d'articles sur l'API REST:

Introduction à l'API REST - Services Web RESTful
Différences entre REST et SOAP
Développement d'API REST - qu'est-ce que Contract First (contrat d'abord)?
Développement d'API REST - qu'est-ce que Code First (code first)?
API REST - Qu'est-ce que HATEOAS?
Recommandations de l'API REST - Exemples de conception de services Web dans Java et Spring

Utilisez l'approche du consommateur d'abord

Qui utilisera votre service? Services aux consommateurs.

Considérez-vous le service du point de vue du consommateur?

Si vous développez une API, votre consommateur peut-il comprendre votre API?
Si vous publiez vos ressources, le consommateur peut-il les trouver et y accéder?
Le consommateur peut-il comprendre vos URI?
Quel type de service proposez-vous?
S'agit-il d'une application mobile ou d'une application web?
À quels consommateurs vous attendez-vous et ces types de consommateurs peuvent-ils changer à l'avenir?
Si vous implémentez quelque chose comme HATEOAS, réfléchissez à la façon dont vos clients l'utiliseront avant de l'implémenter.

La chose la plus importante est d'avoir une excellente documentation
Facilitez la tâche de vos clients pour vous faire gagner du temps.
Plus les consommateurs peuvent faire seuls, moins de travail pour vous.

Chaque fois que vous avez une discussion ou une révision de service, mettez les exigences des clients en premier lieu.

Utilisez l'approche du contrat d'abord

Qu'est-ce qu'un contrat?

Le créateur du service Web est considéré comme un fournisseur de services . Une application qui utilise un service Web est un consommateur du service . Un contrat est un accord entre un fournisseur et un consommateur sur un service.

Afin d'utiliser correctement le service, le consommateur du service doit bien comprendre le contrat. Le contrat comprend des détails sur de nombreux aspects du service, tels que:

Comment appeler un service Web?
Quel type de transport est utilisé?
Quelles sont les structures de demande et de réponse?

Cela s'appelle également une définition de service .

Dans l'approche du contrat d'abord, vous définissez d'abord un contrat de service, puis implémentez uniquement le service.

Contrat d'abord avec WSDL

Par exemple, lorsque vous définissez des services Web SOAP, vous utilisez WSDL pour définir le contrat.

Le WSDL détermine quels sont les points de terminaison de service, les opérations que vous publiez et les structures de demande et de réponse.

Contrat d'abord avec Swagger / Open API

Lorsque vous utilisez des services Web RESTful, Swagger est un outil populaire pour documenter vos services Web.

Swagger vous permet de déterminer les ressources que vous fournissez dans le cadre de votre API. Il inclut les détails de chaque opération, par exemple, si elle utilise XML, JSON ou les deux. Un plan de réponse est également là.

Il donne également des informations détaillées sur les codes de réponse qu'il prend en charge. Vous pouvez également voir que cette ressource particulière, / jpa / users :

prend en charge le fonctionnement GET. En fait, il prend également en charge l'opération POST:

Le schéma de réponse, si cette ressource est disponible, sera:

La définition de l'objet Utilisateur est présente dans l'accord Swagger comme:

Il comprend des attributs: birthDate , id , name et un tableau de messages de messages. Certains champs contiennent également un champ de description.

Dans l'approche du contrat d'abord, avant d'implémenter le service, vous créez manuellement ou à l'aide de l'application la définition créée par Swagger.

Avantages de l'approche du contrat d'abord

En utilisant l'approche du contrat d'abord, vous pensez à vos clients et à la façon dont ils peuvent utiliser ce service. Vous n'êtes pas initialement inquiet des détails de mise en œuvre.

Si, à un stade précoce, vous accordez une grande importance à la mise en œuvre, les détails techniques pénètrent la définition de votre service.

Vous devez vous assurer que la définition de votre service ne dépend pas de la plate-forme que vous utilisez, que ce soit Java, .NET ou toute autre.

Définir les normes d'organisation pour l'API REST

YARAS est une directive importante pour vos normes organisationnelles.

YARAS signifie Yet Another RESTful API Standard . YARAS fournit les normes, directives et conventions à suivre lors du développement de services Web RESTful. Il donne des recommandations pour les choses suivantes:

Comment nommer vos services
Comment structurer votre demande et votre réponse
Comment mettre en œuvre le filtrage, le tri, la pagination et d'autres actions
Comment aborder le versioning
Comment devez-vous aborder la documentation de l'API

Approche unifiée du développement des services

Vous devez résoudre de nombreux problèmes complexes avant de commencer à concevoir des services Web RESTful. Tout ce qui précède, vous devez le savoir.

Le leadership de votre organisation ne voudra pas que les équipes qui traitent de ressources différentes aient des approches différentes de ces choses.

Par exemple, il n'est pas souhaitable que Team-A organise le contrôle de version en fonction des paramètres de requête et Team-B utilise le contrôle de version en fonction de l'URI.

Par conséquent, il est important que vous ayez clairement défini des normes organisationnelles pour votre approche des services Web RESTful.

Personnalisation de YARAS SOUS les besoins organisationnels

La bonne chose à propos de YARAS est qu'il peut être personnalisé pour répondre aux besoins spécifiques de l'organisation. Par exemple, vous pouvez:

Configurez à quoi devraient ressembler les corps de demande et de réponse.
Choisissez un système de contrôle de version spécifique

Étant donné que YARAS a une couverture assez complète, vous pouvez être sûr que vous n'avez manqué aucune décision importante.

Choix d'un cadre standard d'entreprise API REST

Les frameworks typiques utilisés pour créer des services Web RESTful dans le monde Java sont Spring MVC, Spring REST et JAX-RS.

Si vous créez un framework / archétype / application de référence spécifique à l'organisation qui adhère aux normes d'organisation communes en plus de votre plate-forme API REST préférée, cela permettra aux équipes d'adhérer facilement aux normes communes.

Les caractéristiques typiques incluent:

Structures de demande et de réponse
Gestion des erreurs
filtrage
Chercher
Versioning
Prise en charge des fausses réponses
Hateoas

Le cadre standard fournit une approche unifiée de la conception et de la mise en œuvre des services dans toute l'organisation.

Gestion d'API REST décentralisée

Créez un groupe d'experts parmi les équipes créant l'API REST et formez une équipe de gestion. L'équipe est responsable de

Amélioration des normes API REST
Création / conception de votre infrastructure API REST

Utilisation généralisée de HTTP

Chaque fois que vous pensez aux services Web RESTful, pensez au HTTP.

HTTP possède toutes les fonctionnalités qui vous aident à créer d'excellents services Web.

Utilisez les bonnes méthodes de requête HTTP

Pensez aux méthodes de requête HTTP que vous devez utiliser. Lorsque vous pensez à implémenter une opération, déterminez la ressource sur laquelle elle doit être effectuée, puis recherchez la méthode de requête HTTP appropriée. Récupérez-vous des détails, créez-vous quelque chose, mettez-vous à jour quelque chose existant ou supprimez-vous un existant?

Utilisation de méthodes HTTP:

OBTENIR pour obtenir
POST pour créer
PUT à mettre à jour
SUPPRIMER pour supprimer
PATCH pour les mises à jour partielles

Utilisez l'état de réponse HTTP approprié

Lorsque vous effectuez l'opération, assurez-vous de renvoyer l'état de réponse correct.

Par exemple, lorsqu'une ressource spécifique n'est pas trouvée, ne lancez pas d'exception de serveur. Envoyez plutôt le code de réponse approprié dans un message de réponse, tel que 404 .

S'il y a vraiment une exception de serveur, renvoyez le code 500 .

Si la validation échoue, envoyez le code de la demande non valide.

Focus sur la performance

Chaque ressource peut avoir plusieurs représentations - au format XML ou JSON. Le consommateur de services peut choisir la présentation de son choix.

Le service renvoie 3 utilisateurs lorsque nous envoyons une demande GET. Dans ce cas, nous obtenons la représentation JSON de la ressource / users .

Lorsque le consommateur n'indique pas de vue préférée, nous utilisons JSON.

Le consommateur peut envoyer un en-tête Accept pour indiquer la vue.

Le corps de la réponse a désormais un contenu XML:

Utilisez le pluriel

Utilisez toujours le pluriel lorsque vous nommez des ressources.

Regardons un exemple simple. Supposons que nous ayons un service qui héberge une ressource utilisateur. Ce qui suit décrit comment y accéder:

Créer un utilisateur: POST / utilisateurs
Supprimer un utilisateur: SUPPRIMER / utilisateurs / 1
Obtenez tous les utilisateurs: GET / utilisateurs
Obtenez un utilisateur: GET / users / 1

La préférence de plusieurs utilisateurs par rapport à l'utilisateur utilisateur rend l'URI plus lisible.

Par exemple, si nous utilisons / user au lieu de / users pour obtenir, GET / user ne transmet pas le bon message au lecteur.

Créer une bonne documentation

Les consommateurs doivent comprendre comment faire le meilleur usage du service, et la meilleure façon de les aider est de créer une bonne documentation.

Les services Web SOAP peuvent utiliser la fonctionnalité WSDL, tandis que les services Web RESTful ont des options Swagger (désormais la norme de documentation Open API).

Le choix d'un format n'est qu'une partie de la création d'une bonne documentation. Ce qui est également important, c'est de fournir la bonne quantité d'informations pour aider le consommateur.

La documentation doit être complète et inclure les points suivants:

Qu'est-ce qu'une structure de demande et de réponse?
Comment un consommateur doit-il s'authentifier?
Quelles sont les limites d'utilisation?
Indiquez tous les types de messages de réponse et les codes d'état correspondants qui peuvent être attendus du service.

Créer un portail de documentation API REST commun

Il serait utile d'avoir un portail de documentation API REST commun à l'ensemble de l'organisation. Jetez un œil à l'un de ces portails:

Un tel portail regroupe toutes les ressources disponibles dans l'organisation. Avoir une interface utilisateur telle que l'interface utilisateur Swagger aura ses avantages supplémentaires. À l'aide de l'interface utilisateur Swagger, vous pouvez voir la documentation plus en détail:

Cela peut être utilisé même par des utilisateurs non techniques. Les informations fournies ici comprennent:

Format de réponse attendu
Type de contenu
Codes de réponse pris en charge

Le format de la documentation dans le style d'une demande / réponse en direct peut également être intéressant.

Prise en charge des versions

Le contrôle de version entraîne une grande complexité pour un service Web. Il est très difficile de gérer plusieurs versions différentes du même service Web. Essayez d'éviter cela autant que possible.

Cependant, dans certains scénarios, le contrôle de version est inévitable.

Commençons par regarder un exemple de service. Supposons que nous ayons initialement défini un service qui a la classe PersonV1 comme suit:

Cette version de la classe ne prend pas en compte le fait qu'un nom peut avoir plusieurs sous-sections, telles que le prénom et le nom. Vérifiez ceci:

La deuxième version de la classe source a été mise à jour pour corriger cette anomalie:

Nous ne pouvons pas transférer immédiatement l'ensemble du service pour utiliser PersonV2 ! Il est possible que d'autres consommateurs attendent des réponses au format PersonV1 .

C'est là que le contrôle de version est requis.

Voyons maintenant les options que nous avons pour le contrôle de version de ces deux ressources.

Utilisation de différents URI

Nous avons une option: utiliser différents URI pour ces différentes ressources. Dans le code d'examen ci-dessous, nous utilisons les URI v1 / personne et v2 / personne pour les distinguer:

Si vous exécutez une demande GET pour la ressource v1 / personne :

Vous recevrez des informations correspondant à la v1 . Pour une autre ressource:

Utilisation du paramètre de requête

La deuxième méthode de contrôle de version utilise le paramètre de requête:

Dans l'URI / personne / param , si nous envoyons le paramètre avec version = 1 , nous retournons une ressource de type PersonV1 :

Pour le même URI, le paramètre avec version = 2 renvoie une ressource de type PersonV2 :

Cette méthode est appelée versioning à l'aide de paramètres de requête.

Utilisation d'un en-tête (en-tête)

Une autre façon de procéder consiste à contrôler la version en spécifiant un titre. Ici, nous utilisons un en-tête appelé X-API-VERSION et marquons l'URI comme / person / header . Lorsque la valeur d'en-tête est 1 , une ressource de type PersonV1 est renvoyée :

Lorsque sa valeur est 2 , une ressource de type PersonV2 est récupérée:

Nous utilisons l'attribut dans l'en-tête de demande pour effectuer le contrôle de version pour nous.

Utilisation de l'en-tête d'acceptation

La dernière méthode pour créer des versions utilise l'en-tête Accepter. Si le consommateur inclut les informations de première version dans l'en-tête Accept de la demande GET, la ressource suivante est renvoyée:

Sinon, une ressource de type PersonV2 est retournée :

Cette méthode de contrôle de version est appelée Accepter la version d'en-tête ou Version de type de support , car les types MIME sont généralement le contenu de l'en-tête Accepter.

Comparaison des méthodes de contrôle de version

Jusqu'à présent, nous avons vu quatre types de méthodes dans les versions:

Utilisation de différents URI
Utilisation du paramètre de requête
Utilisation de l'en-tête
Utilisation de Accept Header / Media Type

Lequel est le meilleur? La vérité est qu'il n'y a pas de réponse unique à cette question. Le fait est que différents géants de l'Internet fréquentent différents types de versions.

Utilisation de différents URI - Twitter
Utilisation du paramètre de requête - Amazon
Utilisation d'un en-tête - Microsoft
Utilisation de Accept Header / Media Type - GitHub

Vous devez évaluer ces quatre options en fonction de vos besoins spécifiques. Il y a un certain nombre de facteurs importants à considérer:

Pollution URI : En contrôlant les versions à l'aide d'URI et de paramètres de requête, nous finissons par polluer l'espace URI. En effet, nous ajoutons des préfixes et des suffixes aux chaînes principales de l'URI. Le contrôle de version à l'aide d'un en-tête évite cela.
Utilisation abusive des en-têtes HTTP . Dans le cas du contrôle de version utilisant des en-têtes et le type de support, les en-têtes HTTP sont mal utilisés car ils n'étaient pas initialement destinés au contrôle de version.
Mise en cache : une ressource est identifiée par son URI. Toutefois, si vous n'utilisez pas d'URI pour déterminer sa version, mais utilisez un mécanisme basé sur l'en-tête, les informations de version ne peuvent pas être mises en cache. Si la mise en cache HTTP est importante pour vous, utilisez le contrôle de version basé sur un URI ou un paramètre de demande.
Exécutabilité de la demande de navigateur : le versioning basé sur le titre et le type de support nécessite des outils comme Postman. Cependant, si les consommateurs de services ne sont pas techniquement avertis, il est préférable d'utiliser le contrôle de version basé sur un URI ou un paramètre de requête.
Documentation API : Vous devez également réfléchir à la façon dont vous souhaitez documenter vos API. Le contrôle de version basé sur l'URI et le paramètre de requête est plus facile à documenter que les deux autres types de contrôle de version.

Comprenez qu'il n'y a pas de solution idéale unique!

Pensez à la gestion des erreurs

Lorsqu'un consommateur soumet une demande à un service, il est important qu'il reçoive la bonne réponse. Chaque fois que quelque chose se passe mal, il est important d'envoyer une réponse appropriée.

Lorsqu'un consommateur demande une ressource inexistante

Si nous envoyons une demande GET pour rechercher un utilisateur existant, nous obtenons la réponse suivante:

Si vous recherchez un utilisateur inexistant:

Ce que vous obtenez est le statut 404 Not Found . Il s'agit d'une bonne gestion des erreurs car elle détermine correctement que la ressource n'a pas été trouvée et ne renvoie pas d'erreur de serveur.

Envoyons maintenant une requête GET à un URI inexistant:

Comme vous pouvez le voir, vous obtenez 404 statuts de réponse non trouvés . Une URL non valide indique une ressource qui n'existe pas.

Statuts de réponse importants

200 - succès
404 - ressource introuvable
400 - demande non valide (par exemple, erreur de validation)
201 - créé
401 - non autorisé (si l'authentification échoue)
500 - erreur de serveur

Détails de l'erreur dans le corps de réponse

Cela est utile si vous disposez d'une structure d'exception standard lors du développement de votre service.

Pour des erreurs spécifiques, des structures de réponse spécifiques peuvent être renvoyées au consommateur, ce qui peut être la norme dans toute l'organisation. Assurez-vous que la réponse d'erreur est également lisible pour les consommateurs, sans confusion.

Utilisation de la documentation Swagger ou Open API

Swagger fournit l'un des formats de documentation les plus populaires pour les services Web RESTful. Aujourd'hui, il est soutenu par diverses organisations et est utilisé dans un grand nombre de services. Nous examinons ici deux aspects principaux de Swagger: