Discussion :

[boboss123]

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 :

Sélectionner tout - Visualiser dans une fenêtre à part

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 :

Sélectionner tout - Visualiser dans une fenêtre à part

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 :

Sélectionner tout - Visualiser dans une fenêtre à part

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 :

Sélectionner tout - Visualiser dans une fenêtre à part

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 :

Sélectionner tout - Visualiser dans une fenêtre à part

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

[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 :

Sélectionner tout - Visualiser dans une fenêtre à part

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

[boboss123]

Hello,

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 :

Sélectionner tout - Visualiser dans une fenêtre à part

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 :

Sélectionner tout - Visualiser dans une fenêtre à part

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 :

Sélectionner tout - Visualiser dans une fenêtre à part

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 ?

[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 JSON :

Sélectionner tout - Visualiser dans une fenêtre à part

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!

[boboss123]

ok merci