Appendix A. Resource Representation and Representation Data

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

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.

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.

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

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.

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

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.

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

HTTP/1.1 400 Bad Request

Figure 4: An Error Response for Malformed Content

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.

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

Figure 5: Request for Partial Content

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).

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

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].

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

Figure 7: HEAD Request

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

Figure 8: Response to HEAD Request (Empty Content)

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.

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

{"author": "Camilleri"}

Figure 9: POST Request

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