API REST : bonnes pratiques

Version imprimable

Bonjour,

J'ai lu pas mal de documentation sur la création d'API REST mais il y a pas mal d'auteurs qui se contredisent.
J'aimerai donc des clarifications sur les bonnes pratiques à utiliser.

##############################
Méthode HTTP : certaines personnes disent que pour envoyer des données, il faut utiliser uniquement des POST alors que d'autres préconisent d'utiliser POST (pour la création), PUT (pour la modification), DELETE (pour la supression)
=> qu'elle est la meilleure méthode ? on peut toutes les utiliser ? pourquoi ?

##############################
Structure de l'URL, j'ai vu plusieurs méthodes pour envoyer des commandes :
Code:

1 2 3 // {ids} = liste des id des ressources (utilisation du séparateur ",") POST api/<ressources>/{ids}/<ressources_enfants>/{ids}/action?key1=value1&key2=value2
Code:

1 2 3 4 5 6 // {ids} = liste des id des ressources (utilisation du séparateur ",") POST api/<ressources>/{ids}/<ressources_enfants>/{ids}/action Envoie des paramètres en x-www-form-url-encoded key1=value1&key2=value2
Code:

1 2 3 4 5 6 // {ids} = liste des id des ressources (utilisation du séparateur ",") POST api/<ressources>/{ids}/<ressources_enfants>/{ids}/action Envoie des paramètres en form-data key1=value1&key2=value2
Code:

1 2 3 4 5 6 7 8 9 // {ids} = liste des id des ressources (utilisation du séparateur ",") POST api/<ressources>/{ids}/<ressources_enfants>/{ids}/action // Envoie des paramètres en JSON { key1 : value1, key2 : value2 }
Code:

1 2 3 4 5 6 7 8 9 10 11 12 // {ids} = liste des id des ressources (utilisation du séparateur ",") // {action} = POST/PUT/DELETE selon l'action désirée {action} api/<ressources>/{ids}/<ressources_enfants>/{ids} // Envoie des paramètres en JSON { key1 : value1, key2 : value2 } // Mais comment gérer si on veut faire des actions spécifiques ?
Est-ce qu'il y a des méthode à proscrire ? laquelle est la meilleure (la plus simple d'utilisaiton pour l'utilisateur) ? pourquoi ?

##############################
Pour les informations retournées par le serveur, certaines personnes renvoie un objet JSON contenant le message d'erreur avec le code d'erreur dans le header HTTP alors que d'autre renvoie un objet JSON contenant le code d'erreur et le message.
=> les deux pratiques sont viables ? laquelle est la meilleure ? pourquoi ?

Merci d'avance

05/04/2019, 11h23
kevin254kl

Salut,

Il-y a un standard avec openapi https://github.com/OAI/OpenAPI-Speci...2.md#httpCodes
Pour POST https://developer.mozilla.org/fr/doc...P/M%C3%A9thode normalement c'est pour l'ajout et PUT pour le remplacement, après tant qu'on utilise pas une requête http delete pour ajouter :)
Oui ont peut toutes les utiliser, selon ton api ou web service pour donner en lisibilité pour le client de cette api, si je prends une api et que je vois delete sans allez voir la doc je sais que ce sera pour supprimer, même chose pour put post et get.

Pour les urls ou endpoints je ne sais pas si y'a vraiment une règle fondamental, juste méthode kiss et faire simple:

Code:

api/<ressources>/{ids}/<ressources_enfants>/{ids}/action?key1=value1&key2=value2

ça devient vite illisible si j'ai 30 key? Généralement on utilise du json ou xml.

Voici un exemple d'api que je trouve bien fait https://docs.mollie.com/reference/v2...create-payment
Message d'erreur dans le header! Ouvre ton inspecteur > network
05/04/2019, 12h25
boboss123
Hello,

Citation:

Envoyé par kevin254kl

Pour les urls ou endpoints je ne sais pas si y'a vraiment une règle fondamental, juste méthode kiss et faire simple:

Code:

api/<ressources>/{ids}/<ressources_enfants>/{ids}/action?key1=value1&key2=value2

ça devient vite illisible si j'ai 30 key? Généralement on utilise du json ou xml.

Voici un exemple d'api que je trouve bien fait https://docs.mollie.com/reference/v2...create-payment
Message d'erreur dans le header! Ouvre ton inspecteur > network

Donc imaginons que tu es une liste de maisons et de chats. Si je voulais créer une api qui permettent d'autoriser les chats n°3 et 4 a visiter les maisons n°5 et 6, tu ferais comme ça ?
Code:

1 2 3 4 5 6 7 8 9 url : POST http://server/api/houses { "ids":"5,6", "autorize":{ "cats":{ "ids":"3,4" } } }
Autre Commande valide pur faire la même chose :
Code:

1 2 3 4 5 6 7 8 9 url : POST http://server/api/cats { "ids":"3,4", "autorized":{ "house":{ "ids":"5,6" } } }
L’intérêt que je vois de mettre l'action dans le JSON au lieu d'utiliser les méthodes HTTP (POST, PUT, PATCH, DELETE) est que l'on peut exécuter plusieurs actions dans une requête (ex : autoriser et interdire des chats)... mais ce n'est peut-être pas RESTful ?
05/04/2019, 15h23
emixam16
Bonjour,

Les deux commandes ne me paraissent pas déconnantes sur le principe.

Mais tu devrais utiliser des tableaux en JSON pour faciliter le parsage de la requête.

Autre remarque:
- S'il ne peut y avoir que des chats il est inutile de faire un objet chat dans autorise, un objet suffit (ex: allowedCat)
- S'il peut y avoir autre chose que des chats, tu pourrait faire une colonne type et une colonne id (ou un tableau anonyme si tu veux gagner quelques malheureux octets (je te le déconseille: premature optimization is the root of all evil -- Donald Knuth))

Un exemple s'il peut y avoir des chats et des chiens :
Code:

1 2 3 4 5 6 7 8 url : POST http://server/api/houses { "houseID" : [5,6], "allowed" : [ {"type" : "cat", "id" : 3}, {"type" : "dog", "id" : 4}, ] }
--
Bonne journée!
08/04/2019, 13h39
boboss123

ok merci ;)