Une API RESTful doit-elle avoir un schéma?
On m'a dit récemment qu'une API RESTful appropriée devrait définir un schéma pour les représentations de ressources qu'elle accepte et renvoie. Par exemple XSD pour XML et schéma JSON pour JSON.
Cependant, dans tous les livres et articles sur REST je suis passé par là, cela n'a jamais semblé non seulement important, mais même mentionné.
Quelqu'un pourrait-il fournir des ressources faisant autorité, pour clarifier si nous devrions fournir un schéma lors du développement des API RESTful?
Vous devez définir et communiquer les interfaces de demande et de réponse à votre API RESTful en quelque sorte afin que les appelants sachent ce que vous attendez dans la demande et ce à quoi ils peuvent s'attendre dans une réponse.
API RESTful: schéma vs autre définition d'interface
Que vous utilisiez un schéma (XSD, schéma JSON, etc.), ou certains autres forme (langage naturel, exemples, etc.), ou une combinaison pour définir vos interfaces est à vous de décider. Voici quelques facteurs pour éclairer votre décision:
Comment bien connu d'une convention que vous utiliserez.
Schéma: XSD est une norme W3C utilisée dans de nombreuses industries; JSON Schema est l'alternative bien connue à XSD pour JSON.
Autre: Le langage naturel et les exemples sont viables et très utiles, bien que souvent ambigus ou incomplets.
Quelle convention votre communauté appréciera le plus.
Schéma: Les XSD ont surtout tendance à être davantage appréciés par les communautés qui ont déjà investi dans le développement de XSD standard pour leur industrie.
Autre: Le langage naturel et les exemples ont tendance à être appréciés par les nouveaux arrivants.
Comment automatisable d'un processus de validation que vous utiliserez.
Schéma: Les schémas XSD et JSON offrent une validation automatisée standard.
Autre: Le langage naturel et les exemples nécessitent un effort ad hoc pour la validation.
Quelle est la typologie serrée ou lâche d'une interface que vous utiliserez.
Schéma: XSD et JSON peuvent exprimer une plage de spécificité de type mais brillent lorsqu'une spécificité de type détaillée est souhaitée.
Autre: Le langage naturel et les exemples peuvent transmettre des exigences de type, bien que souvent de manière imprécise.
Considérations supplémentaires sur l'API RESTful
Enfin, notez que vous aurez d'autres décisions à prendre au-delà du schéma par rapport au non-schéma :
- Comment vous allez versionner les interfaces au fil du temps.
- Quelle structure d'URL HTTP, méthodes, codes de réponses, etc. vous utiliserez.
- Faut-il gérer toutes ces considérations en utilisant Swagger , RAML , Apiary , Apigee , ou autre framework API.
Ce sont tous des éléments importants de la communication de votre REST API aux appelants de votre service en plus du schéma par rapport à une autre décision de définition d'interface.
Vous devez documenter votre API RESTful pour ceux qui l'utilisent. Le schéma est plus spécifique à chaque format de données renvoyé, ce qui peut être utile. Voici des exemples de références d'API qui définissent bien les méthodes et les formats de réponse:
L'API Google Maps Geocoding (JSON et XML)
Référence de l'API HTTP SoundCloud
documentation de l'API CloudFlare v4
La plupart du temps, ce que je vois sont des méthodes de demande documentées avec des exemples de réponse montrés et un tableau expliquant à quoi s'attendre (pas si souvent un schéma formel en lui-même). Donnez du sens aux humains.
Ils sont facultatifs. Si vous avez besoin d'un filtrage fin des demandes des utilisateurs en tenant compte à la fois de la syntaxe et de la sémantique du contenu, vous l'utilisez.
- Voici une directive RFC mentionne le schéma XML.
https://tools.ietf.org/html/rfc347
"Le schéma XML (défini dans [41] et [42]) fournit des fonctionnalités supplémentaires pour permettre une spécification plus stricte et plus précise de la syntaxe de protocole autorisée et des spécifications de type de données."
- Voici le brouillon IETF pour le schéma JSON: https://tools.ietf.org/html/draft-zyp-json-schema-04
"Le schéma JSON fournit un contrat pour les données JSON requises pour une application donnée et comment interagir avec elle. Le schéma JSON est destiné à définir la validation, la documentation, la navigation par hyperlien et le contrôle d'interaction des données JSON."
Comme vous pouvez le voir, l'IETF n'a pas accepté cela comme un RFC (c'est toujours un brouillon). Ils pensaient que c'était trop pour un protocole simple comme JSON. Cependant, de nombreux projets open source s'appuient sur ce projet.