Conventions pour les API

Nommage des routes

Les noms de routes d’API doivent comporter uniquement des noms, jamais de verbes et toujours au pluriel (ou toujours au singulier). C’est la méthode HTTP utilisée (d’ailleurs aussi appelée « verbe ») qui fait office de verbe.

Bien :

/auth/token
/users/1

Mal :

/session/create
/users/get/1
/user/1

Exemples :

• POST /cats (pour créer un cat)
• GET /cats (pour récupérer un tableau de cats)
• GET /cats/:id (pour récupérer un cat)
• PUT /cats/:id (pour modifier toutes les propriétés d’un cat)
• PATCH /cats/:id (pour modifier une partie des propriétés d’un cat)
• DELETE /cats/:id (pour effacer un cat)

Les codes HTTP de retour

• 200 : tout s’est bien passé, le serveur envoie le résultat (la ou les ressources demandées pour un GET, la ou les resources modifiées pour un PUT/PATCH, et la ou les ressources supprimées pour un DELETE)
• 201 : tout s’est bien passé, j’ai bien créé la ressource demandée (uniquement pour les requêtes POST)
• 204 : tout s’est bien passé, je n’ai pas de contenu à renvoyer (No Content)
• 400 : je ne comprends pas ce que tu dis, qui que tu sois (qui que tu sois mais identifié)
• 401 : je ne sais pas qui tu es, ou bien je ne pense pas que tu sois la personne que tu prétends être, donc je ne te laisse pas rentrer (et il faut idéalement mettre le header WWW-Authenticate: Bearer dans la réponse)
• 403 : je sais très bien qui tu es, et tel que je te connais, tu vas faire des dégâts, donc je ne te laisse pas rentrer
• 404 : J’ai tout compris, je sais qui tu es (ou je m’en moque) mais je n’ai pas ce que tu veux
• 409 : Conflit. J'ai bien compris ce que tu voulais créer mais cette ressource existe déjà, je ne peux pas l'écraser ou modifier telle que tu le demandes. (exemple: création d'un document avec un id de référence existante)
• 429 : je sais qui tu es (ou je m’en moque) mais tu m’as déjà demandé trop de choses, je ne peux plus t’aider pour l’instant, il faut que je m’occupe aussi de servir les autres
• 500 : j’ai compris ta requête, mais j’ai un gros problème pour y répondre : je ne sais pas faire

Il y en a évidemment beaucoup d’autres, cf. httpstatuses.com.

Les fichiers .rest (ou .http)

Les fichiers .rest ou .http sont des fichiers qui permettent de facilement tester des API.

Voici un exemple :

@protocol = http
@host = localhost
@port = 3000
@apiPrefix = /api/v1
@baseUrl = {{protocol}}://{{host}}:{{port}}{{apiPrefix}}

###

{{baseUrl}}/version

###
# @name login
POST {{baseUrl}}/auth/token HTTP/1.1
Content-Type: application/json

{
  "email": "admin@example.com",
  "password": ""53CR37P455!"
}

###
POST {{baseUrl}}/docs HTTP/1.1
Content-Type: application/json
Authorization: Bearer {{login.response.body.token}}

{
  "title": "Conventions",
  "description": "Ensemble des conventions (fortement) recommandées pour les projets de la Fabrique Numérique",
  "tags": ["conventions", "javascript", "typescript"],
  "content": "Lorem ipsum dolor sit amet, consectetur"
}

###
PATCH  {{baseUrl}}/docs/1 HTTP/1.1
Content-Type: application/json
Authorization: Bearer {{login.response.body.token}}

{
  "tags": ["conventions", "javascript", "typescript", "dossiers"],
}

###
DELETE  {{baseUrl}}/docs/1 HTTP/1.1
Authorization: Bearer {{login.response.body.token}}

REST CLient est une extension pour Visual Studio Code qui permet de (très) facilement tester des requêtes d’API RESTful.

Cf. la page dédiée

Pour JetBrains, regardez cette page