Les 10

Meilleures REST API

Pratiques
Pour Une
Meilleure GET POST PUT

RESTful API
 Resource GET

CREATE POST

1. Utiliser des
UPDATE PUT
noms au lieu des
verbes DELETE

NE PAS UTILISER
/getAllCars
/createNewCar
/deleteAllRedCars
 UTILISER LES MÉTHODES PUT, POST, ET
DELETE AU LIEU DE LA MÉTHODE GET POUR

2. La méthode MODIFIER L'ÉTAT.

GET et les
NE PAS UTILISER GET POUR LES
paramètres de la CHANGEMENTS D'ÉTAT.
GET /users/123?activate or

requête ne GET /users/123/activate

doivent pas
modifier l'état
3. Utiliser des
NE PAS UTILISER QUE DES NOMS AU
PLURIEL POUR TOUTES LES RESSOURCES

noms au pluriel /employees

/users
à la place de
à la place de
/employee
/user
/products à la place de /product
/items à la place de /item
 GARDER TOUJOURS L'UTILISATION DES
NOMS AU PLURIEL MÊME POUR LES
SOUS-RESSOURCES
4. Utiliser des
sous-ressources GET /categories/123/products/
Renvoie une liste de produits pour la
pour les catégorie 123

relations GET /categories/123/products/4

Renvoie le produit #4 pour la catégorie
123
 LE FORMAT DOIT ÊTRE SPÉCIFIÉ DANS LE
HTTP-HEADER

5. Utilisez HTTP Content-Type: définit le format de la requête.

Accept: définit une liste de formats de réponse

headers pour acceptables.

Expires: Un en-tête de réponse indiquant le délai

les formats de
après lequel la réponse est considérée comme
périmée.
Cache-Control: Un en-tête de réponse qui indique
serialization la directive de mise en cache pour la demande.
Authorization: Un en-tête de demande qui
contient une chaîne utilisée pour authentifier les
demandes
Content-Length: La longueur (en octets) du corps
de la demande ou de la réponse.
...
 C'EST UNE CONTRAINTE DE L'ARCHITECTURE
D'UNE APPLICATION REST QUI LA DISTINGUE
DES AUTRES ARCHITECTURES APPLICATIVES
RÉSEAU.
6. Utiliser {
"id": 123,

HATEOAS "manufacturer": "TESLA",

"model": "Model 3",
"drivers": [

Hypermedia As {
"id": "23",

The Engine Of
"name": "Jalal M.",
"links": [
{

Application State.
"rel": "self",
"href": "/api/v1/drivers/23"
}
]
}
]
}
 UN FILTRAGE
GET /cars?color=black Renvoie une liste des voitures
noires

7. Fournir un GET /cars?seats>=2 Renvoie une liste de voitures avec

un minimum de 2 sièges

filtrage, un tri, UN TRI

une sélection de
GET /cars?sort=-manufactorer,+type

champs, et une UNE SÉLECTION DE CHAMPS

GET /cars?fields=manufacturer,model,id,color

pagination pour Renvoie une liste de voitures avec les champs

fabricant, modèle, identifiant, couleur

les collections UNE PAGINATION

GET /cars?offset=10&limit=5
Renvoie une liste de voitures de l'enregistrement #11 à
l'enregistrement #15
 UNE PAGINATION
Pour renvoyer le total des entrées à l'utilisateur,

7. Fournir un utilisez HTTP header personnalisé : X-Total-Count.

Les liens vers la page suivante ou précédente doivent

filtrage, un tri, également être fournis dans le lien HTTP header

une sélection de Le lien:

champs, et une
<https://distinktec.com/sample/api/v1/products?
offset=15&limit=5>; rel="next",
<https://distinktec.com/sample/api/v1/products?
pagination pour offset=50&limit=3>; rel="last",
<https://distinktec.com/sample/api/v1/products?

les collections offset=0&limit=5>; rel="first",

<https://distinktec.com/sample/api/v1/products?
offset=5&limit=5>; rel="prev",
 RENDRE LA VERSION DE L'API
OBLIGATOIRE ET NE PAS PUBLIER UNE API
NON VERSIONNÉE

8. Version de /blog/api/v1

votre API
UTILISER UN NOMBRE ORDINAL SIMPLE ET
ÉVITER LA NOTATION PAR POINTS TEL QUE
2.5

/blog/api/v2.5
 UTILISER LES CODES D'ÉTAT HTTP
La norme HTTP fournit plus de 70 codes d'état
pour décrire les valeurs de retour. Nous n'avons
pas besoin de tous, mais il faut en utiliser au
9. Gérer les moins 10.

Erreurs Avec UTILISER DES CHARGES UTILES D'ERREUR

Toutes les exceptions doivent être mappées dans une

les codes d'état charge utile (Paylaod) d'erreur. Exemple de charge utile
JSON :

HTTP {
"errors": [{
"userMessage": "Désolé, la ressource demandée n'existe
pas",
"internalMessage": "No product found in the database",
"code": 34,
"more info":
"http://distinktec.com/blog/api/v1/errors/12345"
}]
}
 LORSQUE VOUS UTILISEZ DES MÉTHODES
HTTP,TENEZ COMPTE DES ASPECTS DE
SÉCURITÉ. POUR UNE SÉCURITÉ RENFORCÉE,
CERTAINS PARE-FEU N'AUTORISENT PAS LE
TRAFIC HTTP PUT OU DELETE .

10. Autoriser la Pour prendre en charge une API RESTful

avec ces limitations, l'API a besoin d'un

surcharge de la moyen de remplacer la méthode HTTP

méthode HTTP
Utiliser les champs d'en-tête HTTP X-Method-Override ou
X-HTTP-Method-Override pour canaliser une requête PUT
ou DELETE via une requête POST .
Utiliser les paramètres d'URI x-method-override oux-http-
method-override.

Exemple :

POST /api/v1/categories?...&x-method-override=PUT
 Avez-vous
des questions?
Commentez / Contactez-nous / Suivez-nous