HTTP
HTTP pour les API
Recherche…
Remarques
Les API HTTP utilisent un large éventail de verbes HTTP et retournent généralement des réponses JSON ou XML.
Créer une ressource
Tout le monde n'est pas d'accord sur la méthode la plus sémantiquement correcte pour la création de ressources. Ainsi, votre API pourrait accepter les requêtes POST ou PUT , ou l'une ou l'autre.
Le serveur doit répondre par 201 Created si la ressource a été créée avec succès. Choisissez le code d'erreur le plus approprié s'il ne l'était pas.
Par exemple, si vous fournissez une API pour créer des enregistrements d'employés, la demande / réponse peut ressembler à ceci:
POST /employees HTTP/1.1
Host: example.com
Content-Type: application/json
{
"name": "Charlie Smith",
"age": 38,
"job_title": "Software Developer",
"salary": 54895.00
}
HTTP/1.1 201 Created
Location: /employees/1/charlie-smith
Content-Type: application/json
{
"employee": {
"name": "Charlie Smith",
"age": 38,
"job_title": "Software Developer",
"salary": 54895.00
"links": [
{
"uri": "/employees/1/charlie-smith",
"rel": "self",
"method": "GET"
},
{
"uri": "/employees/1/charlie-smith",
"rel": "delete",
"method": "DELETE"
},
{
"uri": "/employees/1/charlie-smith",
"rel": "edit",
"method": "PATCH"
}
]
},
"links": [
{
"uri": "/employees",
"rel": "create",
"method": "POST"
}
]
}
L'inclusion des champs JSON des links dans la réponse permet au client d'accéder aux ressources liées à la nouvelle ressource et à l'application dans son ensemble, sans avoir à connaître leurs URI ou méthodes au préalable.
Modifier une ressource
La modification ou la mise à jour d'une ressource est un objectif commun des API. Les modifications peuvent être effectuées en envoyant des requêtes POST , PUT ou PATCH à la ressource respective. Bien que POST soit autorisé à ajouter des données à la représentation existante d'une ressource, il est recommandé d'utiliser PUT ou PATCH car elles transmettent une sémantique plus explicite.
Votre serveur doit répondre avec 200 OK si la mise à jour a été effectuée ou 202 Accepted si l'application n'a pas encore été effectuée. Choisissez le code d'erreur le plus approprié s'il ne peut pas être complété.
Mises à jour complètes
PUT a la sémantique de remplacer la représentation actuelle par la charge utile incluse dans la requête. Si la charge utile n'est pas du même type de représentation que la représentation actuelle de la ressource à mettre à jour, le serveur peut décider de l'approche à suivre. RFC7231 définit que le serveur peut soit
- Reconfigurer la ressource cible pour refléter le nouveau type de média
- Transforme la représentation PUT en un format compatible avec celui de la ressource avant de l'enregistrer en tant que nouvel état de ressource
- Rejeter la demande avec une réponse
415 Unsupported Media Typeindiquant que la ressource cible est limitée à un ensemble (spécifique) de types de média.
Une ressource de base contenant une représentation JSON HAL comme ...
{
"name": "Charlie Smith",
"age": 39,
"job_title": "Software Developer",
"_links": {
"self": { "href": "/users/1234" },
"employee": { "href": "http://www.acmee.com" },
"curies": [{ "name": "ea", "href": "http://www.acmee.com/docs/rels/{rel}", templated": true}],
"ea:admin": [
"href": "/admin/2",
"title": "Admin"
]
}
}
... peut recevoir une demande de mise à jour comme celle-ci
PUT /users/1234 HTTP/1.1
Host: http://www.acmee.com
Content-Type: "application/json; charset=utf-8"
Content-Length: 85
User-Agent: Mozilla/4.0 (compatible; MSIE5.01; Windows NT)
{
"name": "Charlie Gold-Smith",
"age": 40,
"job_title": "Senior Software Developer"
}
Le serveur peut maintenant remplacer l'état de la ressource par le corps de requête donné et changer le type de contenu de application/hal+json à application/json ou convertir le contenu JSON en représentation JSON HAL, puis remplacer le contenu de la ressource. avec la transformée ou rejeter la demande de mise à jour en raison d'un type de support inaplicable avec une réponse 415 Unsupported Media Type type de support 415 Unsupported Media Type .
Il y a une différence entre remplacer le contenu directement ou d'abord transformer la représentation en un modèle de représentation défini, puis remplacer le contenu existant par le contenu transformé. Une demande GET ultérieure renverra la réponse suivante lors d'un remplacement direct:
GET /users/1234 HTTP/1.1
Host: http://www.acmee.com
Accept-Encoding: gzip, deflate
Accept-Language: en-us
User-Agent: Mozilla/4.0 (compatible; MSIE5.01; Windows NT)
ETag: "e0023aa4e"
{
"name": "Charlie Gold-Smith",
"age": 40,
"job_title": "Senior Software Developer"
}
tandis que l'approche de transformation puis de remplacement renverra la représentation suivante:
GET /users/1234 HTTP/1.1
Host: http://www.acmee.com
Accept-Encoding: gzip, deflate
Accept-Language: en-us
User-Agent: Mozilla/4.0 (compatible; MSIE5.01; Windows NT)
ETag: e0023aa4e
{
"name": "Charlie Gold-Smith",
"age": 40,
"job_title": "Senior Software Developer",
"_links": {
"self": { "href": "/users/1234" },
"employee": { "href": "http://www.acmee.com" },
"curies": [{ "name": "ea", "href": "http://www.acmee.com/docs/rels/{rel}", templated": true}],
"ea:admin": [
"href": "/admin/2",
"title": "Admin"
]
}
}
Effets secondaires
Notez que PUT est autorisé à avoir des effets secondaires bien qu'il soit défini comme un fonctionnement idempotent! Ceci est documenté dans RFC7231 comme
Une demande PUT appliquée à la ressource cible peut avoir des effets secondaires sur d'autres ressources . Par exemple, un article peut avoir une URI pour identifier "la version actuelle" (une ressource) distincte des URI identifiant chaque version particulière (des ressources différentes partageant à un moment donné le même état que la ressource de version actuelle). Une demande PUT réussie sur l'URI de la "version actuelle" peut donc créer une nouvelle ressource de version en plus de modifier l'état de la ressource cible et peut également entraîner l'ajout de liens entre les ressources associées.
Produire des entrées de journal supplémentaires n'est généralement pas considéré comme un effet secondaire, car il ne s'agit certainement pas d'un état d'une ressource en général.
Mises à jour partielles
RFC7231 mentionne ceci concernant les mises à jour partielles:
Les mises à jour de contenu partielles sont possibles en ciblant une ressource identifiée séparément avec un état recouvrant une partie de la ressource plus grande ou en utilisant une méthode différente qui a été spécifiquement définie pour les mises à jour partielles (par exemple, la méthode PATCH définie dans RFC5789 ).
Les mises à jour partielles peuvent donc être effectuées en deux versions:
- Demander à une ressource d'intégrer plusieurs sous-ressources plus petites et de ne mettre à jour qu'une sous-ressource respective au lieu de la ressource complète via
PUT - Utiliser
PATCHet indiquer au serveur quoi mettre à jour
Mise à jour partielle avec état superposé
Si une représentation d'utilisateur doit être partiellement mise à jour en raison du déplacement d'un utilisateur vers un autre emplacement, au lieu de mettre à jour l'utilisateur directement, la ressource associée doit être mise à jour directement, ce qui correspond à une mise à jour partielle de la représentation de l'utilisateur.
Avant le déplacement, un utilisateur avait la représentation suivante
GET /users/1234 HTTP/1.1
Host: http://www.acmee.com
Accept: application/hal+json; charset=utf-8
Accept-Encoding: gzip, deflate
Accept-Language: en-us
User-Agent: Mozilla/4.0 (compatible; MSIE5.01; Windows NT)
ETag: "e0023aa4e"
{
"name": "Charlie Gold-Smith",
"age": 40,
"job_title": "Senior Software Developer",
"_links": {
"self": { "href": "/users/1234" },
"employee": { "href": "http://www.acmee.com" },
"curies": [{ "name": "ea", "href": "http://www.acmee.com/docs/rels/{rel}", templated": true}],
"ea:admin": [
"href": "/admin/2",
"title": "Admin"
]
},
"_embedded": {
"ea:address": {
"street": "Terrace Drive, Central Park",
"zip": "NY 10024"
"city": "New York",
"country": "United States of America",
"_links": {
"self": { "href": "/address/abc" },
"google_maps": { "href": "http://maps.google.com/?ll=40.7739166,-73.970176" }
}
}
}
}
Lorsque l'utilisateur se déplace vers un nouvel emplacement, il met à jour ses informations de localisation comme suit:
PUT /address/abc HTTP/1.1
Host: http://www.acmee.com
Content-Type: "application/json; charset=utf-8"
Content-Length: 109
User-Agent: Mozilla/4.0 (compatible; MSIE5.01; Windows NT)
{
"street": "Standford Ave",
"zip": "CA 94306",
"city": "Pablo Alto",
"country": "United States of America"
}
Avec la sémantique de transformation-avant-remplacement pour le type de média incompatible entre la ressource d'adresse existante et celle de la requête, comme décrit ci-dessus, la ressource d'adresse est maintenant mise à jour et a pour conséquence qu'une requête GET ultérieure sur la ressource utilisateur la nouvelle adresse de l'utilisateur est renvoyée.
GET /users/1234 HTTP/1.1
Host: http://www.acmee.com
Accept: application/hal+json; charset=utf-8
Accept-Encoding: gzip, deflate
Accept-Language: en-us
User-Agent: Mozilla/4.0 (compatible; MSIE5.01; Windows NT)
ETag: "e0023aa4e"
{
"name": "Charlie Gold-Smith",
"age": 40,
"job_title": "Senior Software Developer",
"_links": {
"self": { "href": "/users/1234" },
"employee": { "href": "http://www.acmee.com" },
"curies": [{ "name": "ea", "href": "http://www.acmee.com/docs/rels/{rel}", templated": true}],
"ea:admin": [
"href": "/admin/2",
"title": "Admin"
]
},
"_embedded": {
"ea:address": {
"street": "Standford Ave",
"zip": "CA 94306",
"city": "Pablo Alto",
"country": "United States of America"
"_links": {
"self": { "href": "/address/abc" },
"google_maps": { "href": "http://maps.google.com/?ll=37.4241311,-122.1524475" }
}
}
}
}
Correction de données partielles
PATCH est défini dans RFC5789 et ne fait pas directement partie des spécifications HTTP en soi. Une erreur courante consiste à dire que l' envoi de champs uniquement à mettre à jour est suffisant dans une requête PATCH . La spécification indique donc
La méthode PATCH demande qu'un ensemble de modifications décrites dans l'entité de demande soit appliqué à la ressource identifiée par l'URI de demande. L'ensemble des modifications est représenté dans un format appelé "document de correctif" identifié par un type de média.
Cela signifie qu'un client doit calculer les étapes nécessaires à la transformation de la ressource de l'état A à l'état B et envoyer ces instructions au serveur.
JSON Patch est un type de média populaire basé sur JSON .
Si l'âge et le titre de travail de notre exemple d'utilisateur changent et qu'un champ supplémentaire représentant le revenu de l'utilisateur doit être ajouté, une mise à jour partielle à l'aide de PATCH utilisant JSON Patch peut ressembler à ceci:
PATCH /users/1234 HTTP/1.1
Host: http://www.acmee.com
Content-Type: application/json-patch+json; charset=utf-8
Content-Length: 188
Accept: application/json
If-Match: "e0023aa4e"
[
{ "op": "replace", "path": "/age", "value": 40 },
{ "op": "replace", "path": "/job_title", "value": "Senior Software Developer" },
{ "op": "add", "path": "/salery", "value": 63985.00 }
]
PATCH peut mettre à jour plusieurs ressources à la fois et appliquer les modifications de manière atomique, ce qui signifie que toutes les modifications doivent être appliquées ou aucune, ce qui impose un fardeau transactionnel à l'implémenteur de l'API.
Une mise à jour réussie peut renvoyer quelque chose comme ceci
HTTP/1.1 200 OK
Location: /users/1234
Content-Type: application/json
ETag: "df00eb258"
{
"name": "Charlie Smith",
"age": 40,
"job_title": "Senior Software Developer",
"salary": 63985.00
}
mais n'est pas limité à 200 OK codes de réponse 200 OK seulement.
Pour éviter les mises à jour intermédiaires (modifications effectuées entre la récupération précédente de l'état de représentation et la mise à jour), l'en If-Unmodified-Since tête ETag , If-Match ou If-Unmodified-Since doit être utilisé.
La gestion des erreurs
La spécification de PATCH recommande la gestion des erreurs suivante:
| Type | Code d'erreur |
|---|---|
| Document de correctif mal formé | 400 Bad Request |
| Document de correctif non pris en charge | 415 Unsupported Media Type |
| Demande non traitable, c.-à-d. Si le ressource devient invalide en appliquant le correctif | 422 Unprocessable Entity |
| Ressource introuvable | 404 Not Found |
| Etat conflictuel, c'est-à-dire renommer (déplacer) un champ qui n'existe pas | 409 Conflict |
Modification en conflit, c'est-à-dire si le client utilise un en If-Unmodified-Since tête If-Match ou If-Unmodified-Since dont la validation a échoué. Si aucune condition préalable n'était disponible, le dernier code d'erreur devrait être renvoyé | 412 Precondition Failed ou 409 Conflict |
Modification concomitante, c.-à-d. Si la demande doit être appliquée avant l'acception, les demandes PATCH supplémentaires | 409 Conflict |
Supprimer une ressource
Une autre utilisation courante des API HTTP consiste à supprimer une ressource existante. Cela devrait normalement être fait en utilisant les requêtes DELETE .
Si la suppression a réussi, le serveur doit renvoyer 200 OK ; un code d'erreur approprié s'il ne l'était pas.
Si notre employé Charlie Smith a quitté l'entreprise et que nous voulons maintenant supprimer ses dossiers, cela pourrait ressembler à ceci:
DELETE /employees/1/charlie-smith HTTP/1.1
Host: example.com
HTTP/1.1 200 OK
Content-Type: application/json
{
'links': [
{
'uri': '/employees',
'rel': 'create',
'method': 'POST'
}
]
}
Liste des ressources
La dernière utilisation commune des API HTTP consiste à obtenir une liste des ressources existantes sur le serveur. De telles listes doivent être obtenues en utilisant GET requêtes GET , car elles ne récupèrent que des données.
Le serveur doit renvoyer 200 OK s'il peut fournir la liste, ou un code d'erreur approprié si ce n'est pas le cas.
Voici une liste de nos employés:
GET /employees HTTP/1.1
Host: example.com
HTTP/1.1 200 OK
Content-Type: application/json
{
'employees': [
{
'name': 'Charlie Smith',
'age': 39,
'job_title': 'Software Developer',
'salary': 63985.00
'links': [
{
'uri': '/employees/1/charlie-smith',
'rel': 'self',
'method': 'GET'
},
{
'uri': '/employees/1/charlie-smith',
'rel': 'delete',
'method': 'DELETE'
},
{
'uri': '/employees/1/charlie-smith',
'rel': 'edit',
'method': 'PATCH'
}
]
},
{
'name': 'Donna Prima',
'age': 30,
'job_title': 'QA Tester',
'salary': 77095.00
'links': [
{
'uri': '/employees/2/donna-prima',
'rel': 'self',
'method': 'GET'
},
{
'uri': '/employees/2/donna-prima',
'rel': 'delete',
'method': 'DELETE'
},
{
'uri': '/employees/2/donna-prima',
'rel': 'edit',
'method': 'PATCH'
}
]
}
],
'links': [
{
'uri': '/employees/new',
'rel': 'create',
'method': 'PUT'
}
]
}