Annexe A. Représentation des ressources et données de représentation

The following examples show how representation metadata, content transformations, and methods impact the message and content. These examples a not exhaustive.

Les exemples suivants montrent comment les métadonnées de représentation, les transformations de contenu et les méthodes affectent le message et le contenu. Ces exemples ne sont pas exhaustifs.

Unless otherwise indicated, the examples are based on the JSON object {"hello": "world"} followed by an LF. When the content contains non-printable characters (e.g., when it is encoded), it is shown as a sequence of hex-encoded bytes.

Sauf indication contraire, les exemples sont basés sur l'objet JSON {"hello": "world"} suivi d'un LF. Lorsque le contenu contient des caractères non imprimables (par exemple, lorsqu'il est encodé), il est affiché sous la forme d'une séquence d'octets codés en hexadécimal.

Consider a client that wishes to upload a JSON object using the PUT method. It could do this using the application/json Content-Type without any content coding.

Considérez un client qui souhaite télécharger un objet JSON en utilisant la méthode PUT. Il pourrait le faire en utilisant le Content-Type application/json sans aucun codage de contenu.

PUT /entries/1234 HTTP/1.1
Host: foo.example
Content-Type: application/json
Content-Length: 19

{"hello": "world"}

Figure 1: Request Containing a JSON Object without Any Content Coding

Figure 1 : Requête contenant un objet JSON sans aucun codage de contenu

However, the use of content coding is quite common. The client could also upload the same data with a GZIP coding (Section 8.4.1.3 of [HTTP]). Note that in this case, the Content-Length contains a larger value due to the coding overheads.

Cependant, l'utilisation du codage de contenu est assez courante. Le client pourrait également télécharger les mêmes données avec un codage GZIP (section 8.4.1.3 de [HTTP]). Notez que dans ce cas, le Content-Length contient une valeur plus élevée en raison des surcharges de codage.

PUT /entries/1234 HTTP/1.1
Host: foo.example
Content-Type: application/json
Content-Encoding: gzip
Content-Length: 39

1F 8B 08 00 88 41 37 64 00 FF
AB 56 CA 48 CD C9 C9 57 B2 52
50 2A CF 2F CA 49 51 AA E5 02
00 D9 E4 31 E7 13 00 00 00

Figure 2: Request Containing a GZIP-Encoded JSON Object

Figure 2 : Requête contenant un objet JSON encodé en GZIP

Sending the GZIP-coded data without indicating it via Content-Encoding means that the content is malformed. In this case, the server can reply with an error.

Envoyer les données codées en GZIP sans l'indiquer via Content-Encoding signifie que le contenu est malformé. Dans ce cas, le serveur peut répondre avec une erreur.

PUT /entries/1234 HTTP/1.1
Host: foo.example
Content-Type: application/json

Content-Length: 39

1F 8B 08 00 88 41 37 64 00 FF
AB 56 CA 48 CD C9 C9 57 B2 52
50 2A CF 2F CA 49 51 AA E5 02
00 D9 E4 31 E7 13 00 00 00

Figure 3: Request Containing Malformed JSON

Figure 3 : Requête contenant un JSON malformé

HTTP/1.1 400 Bad Request

Figure 4: An Error Response for Malformed Content

Figure 4 : Une réponse d'erreur pour un contenu malformé

A Range-Request affects the transferred message content. In this example, the client is accessing the resource at /entries/1234, which is the JSON object {"hello": "world"} followed by an LF. However, the client has indicated a preferred content coding and a specific byte range.

Une requête de plage affecte le contenu du message transféré. Dans cet exemple, le client accède à la ressource à /entries/1234, qui est l'objet JSON {"hello": "world"} suivi d'un LF. Cependant, le client a indiqué un codage de contenu préféré et une plage d'octets spécifique.

GET /entries/1234 HTTP/1.1
Host: foo.example
Accept-Encoding: gzip
Range: bytes=1-7

Figure 5: Request for Partial Content

Figure 5 : Requête pour un contenu partiel

The server satisfies the client request by responding with a partial representation (equivalent to the first 10 bytes of the JSON object displayed in whole in Figure 2).

Le serveur satisfait la demande du client en répondant avec une représentation partielle (équivalente aux 10 premiers octets de l'objet JSON affiché en entier dans la figure 2).

HTTP/1.1 206 Partial Content
Content-Encoding: gzip
Content-Type: application/json
Content-Range: bytes 0-9/39

1F 8B 08 00 A5 B4 BD 62 02 FF

Figure 6: Partial Response from a GZIP-Encoded Representation

Figure 6 : Réponse partielle à partir d'une représentation encodée en GZIP

Aside from content coding or range requests, the method can also affect the transferred message content. For example, the response to a HEAD request does not carry content, but this example case includes Content-Length; see Section 8.6 of [HTTP].

Outre le codage de contenu ou les requêtes de plage, la méthode peut également affecter le contenu du message transféré. Par exemple, la réponse à une requête HEAD ne transporte pas de contenu, mais cet exemple inclut Content-Length ; voir la section 8.6 de [HTTP].

HEAD /entries/1234 HTTP/1.1
Host: foo.example
Accept: application/json
Accept-Encoding: gzip

Figure 7: HEAD Request

Figure 7 : Requête HEAD

HTTP/1.1 200 OK
Content-Type: application/json
Content-Encoding: gzip
Content-Length: 39

Figure 8: Response to HEAD Request (Empty Content)

Figure 8 : Réponse à la requête HEAD (contenu vide)

Finally, the semantics of a response might decouple the target URI from the enclosed representation. In the example below, the client issues a POST request directed to /authors/, but the response includes a Content-Location header field indicating that the enclosed representation refers to the resource available at /authors/123. Note that Content-Length is not sent in this example.

Enfin, la sémantique d'une réponse peut découpler l'URI cible de la représentation incluse. Dans l'exemple ci-dessous, le client émet une requête POST dirigée vers /authors/, mais la réponse inclut un champ d'en-tête Content-Location indiquant que la représentation incluse fait référence à la ressource disponible à /authors/123. Notez que Content-Length n'est pas envoyé dans cet exemple.

POST /authors/ HTTP/1.1
Host: foo.example
Accept: application/json
Content-Type: application/json

{"author": "Camilleri"}

Figure 9: POST Request

Figure 9 : Requête POST

HTTP/1.1 201 Created
Content-Type: application/json
Content-Location: /authors/123
Location: /authors/123

{"id": "123", "author": "Camilleri"}

Figure 10: Response with Content-Location Header

Figure 10 : Réponse avec en-tête Content-Location