Conception d'API HTTP

Introduction

Fondations

La section Fondements décrit les principes de conception sur laquelle le reste du guide construit.

Les préoccupations distinctes

Gardez les choses simples lors de la conception en séparant les préoccupations entre les différentes parties du cycle de demande et de réponse. Garder des règles simples pour ceci, permet de se concentrer davantage sur les problèmes plus importants et plus difficiles.

Les demandes et les réponses seront faits pour adresser une ressource ou une collection particulière. Utilisez le chemin pour désigner l'identité, le corps pour transférer le contenu et les en-têtes pour communiquer des métadonnées. Les paramètres de la requête peuvent être utilisé comme un moyen pour transmettre des informations d'en-tête également dans les cas de pointe, mais les en-têtes sont préférés car elles sont plus souples et peuvent transmettre des informations plus diversifiées.

Exiger des connexions sécurisées

En gros toujours utiliser des connextions sécurisées pour les API.

Exiger de versionner votre API dans l'entête Accept

Version et la transition entre les versions est l'un des aspects les plus difficiles de la conception et l'exploitation d'une API. En tant que tel, il est préférable de commencer par des mécanismes en place pour atténuer ce dès le début. Pour éviter la surprise, la rupture des changements aux utilisateurs, il est préférable d'exiger une version être spécifiée avec toutes les demandes. versions par défaut devraient être évitées car elles sont très difficiles, au mieux, de changer à l'avenir. Il est préférable de fournir les spécifications de version dans les en-têtes, avec d'autres métadonnées, en utilisant l'en-tête avec un type de contenu personnalisé, e.g Encaisser .: