Skip to main content

Appendix B. Examples of Unsolicited Digest

The following examples demonstrate interactions where a server responds with a Content-Digest or Repr-Digest field, even though the client did not solicit one using Want-Content-Digest or Want-Repr-Digest.

Some examples include JSON objects in the content. For presentation purposes, objects that fit completely within the line-length limits are presented on a single line using compact notation with no leading space. Objects that would exceed line-length limits are presented across multiple lines (one line per key-value pair) with two spaces of leading indentation.

Checksum mechanisms defined in this document are media-type agnostic and do not provide canonicalization algorithms for specific formats. Examples are calculated inclusive of any space. While examples can include both fields, Content-Digest and Repr-Digest can be returned independently.

B.1. Server Returns Full Representation Data​

In this example, the message content conveys complete representation data. This means that in the response, Content-Digest and Repr-Digest are both computed over the JSON object {"hello": "world"} followed by an LF; thus, they have the same value.

GET /items/123 HTTP/1.1
Host: foo.example

Figure 11: GET Request for an Item

NOTE: '' line wrapping per RFC 8792

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 19
Content-Digest: \
  sha-256=:RK/0qy18MlBSVnWgjwz6lZEWjP/lF5HF9bvEF8FabDg=:
Repr-Digest: \
  sha-256=:RK/0qy18MlBSVnWgjwz6lZEWjP/lF5HF9bvEF8FabDg=:

{"hello": "world"}

Figure 12: Response with Identical Repr-Digest and Content-Digest

B.2. Server Returns No Representation Data​

In this example, a HEAD request is used to retrieve the checksum of a resource.

The response Content-Digest field-value is computed on empty content. Repr-Digest is calculated over the JSON object {"hello": "world"} followed by an LF, which is not shown because there is no content.

HEAD /items/123 HTTP/1.1
Host: foo.example

Figure 13: HEAD Request for an Item

NOTE: '' line wrapping per RFC 8792

HTTP/1.1 200 OK
Content-Type: application/json
Content-Digest: \
  sha-256=:47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=:
Repr-Digest: \
  sha-256=:RK/0qy18MlBSVnWgjwz6lZEWjP/lF5HF9bvEF8FabDg=:

Figure 14: Response with Both Content-Digest and Digest (Empty Content)

B.3. Server Returns Partial Representation Data​

In this example, the client makes a range request and the server responds with partial content.

GET /items/123 HTTP/1.1
Host: foo.example
Range: bytes=10-18

Figure 15: Request for Partial Content

NOTE: '' line wrapping per RFC 8792

HTTP/1.1 206 Partial Content
Content-Type: application/json
Content-Range: bytes 10-18/19
Content-Digest: \
  sha-256=:jjcgBDWNAtbYUXI37CVG3gRuGOAjaaDRGpIUFsdyepQ=:
Repr-Digest: \
  sha-256=:RK/0qy18MlBSVnWgjwz6lZEWjP/lF5HF9bvEF8FabDg=:

"world"}

Figure 16: Partial Response with Both Content-Digest and Repr-Digest

In the response message above, note that the Repr-Digest and Content-Digests are different. The Repr-Digest field-value is calculated across the entire JSON object {"hello": "world"} followed by an LF, and the field appears as follows:

NOTE: '' line wrapping per RFC 8792

Repr-Digest: \
  sha-256=:RK/0qy18MlBSVnWgjwz6lZEWjP/lF5HF9bvEF8FabDg=:

However, since the message content is constrained to bytes 10-18, the Content-Digest field-value is calculated over the sequence "world"} followed by an LF, thus resulting in the following:

NOTE: '' line wrapping per RFC 8792

Content-Digest: \
  sha-256=:jjcgBDWNAtbYUXI37CVG3gRuGOAjaaDRGpIUFsdyepQ=:

B.4. Client and Server Provide Full Representation Data​

The request contains a Repr-Digest field-value calculated on the enclosed representation. It also includes an Accept-Encoding: br header field that advertises that the client supports Brotli encoding.

The response includes a Content-Encoding: br that indicates the selected representation is Brotli-encoded. The Repr-Digest field-value is therefore different compared to the request.

For presentation purposes, the response body is displayed as a sequence of hex-encoded bytes because it contains non-printable characters.

NOTE: '' line wrapping per RFC 8792

PUT /items/123 HTTP/1.1
Host: foo.example
Content-Type: application/json
Accept-Encoding: br
Repr-Digest: \
  sha-256=:RK/0qy18MlBSVnWgjwz6lZEWjP/lF5HF9bvEF8FabDg=:

{"hello": "world"}

Figure 17: PUT Request with Digest

NOTE: '' line wrapping per RFC 8792

HTTP/1.1 200 OK
Content-Type: application/json
Content-Location: /items/123
Content-Encoding: br
Content-Length: 23
Repr-Digest: \
  sha-256=:d435Qo+nKZ+gLcUHn7GQtQ72hiBVAgqoLsZnZPiTGPk=:

8B 08 80 7B 22 68 65 6C 6C 6F
22 3A 20 22 77 6F 72 6C 64 22
7D 0A 03

Figure 18: Response with Digest of Encoded Response

B.5. Client Provides Full Representation Data and Server Provides No Representation Data​

The request Repr-Digest field-value is calculated on the enclosed content, which is the JSON object {"hello": "world"} followed by an LF.

The response Repr-Digest field-value depends on the representation metadata header fields, including Content-Encoding: br, even when the response does not contain content.

NOTE: '' line wrapping per RFC 8792

PUT /items/123 HTTP/1.1
Host: foo.example
Content-Type: application/json
Content-Length: 19
Accept-Encoding: br
Repr-Digest: \
  sha-256=:RK/0qy18MlBSVnWgjwz6lZEWjP/lF5HF9bvEF8FabDg==:

{"hello": "world"}
HTTP/1.1 204 No Content
Content-Type: application/json
Content-Encoding: br
Repr-Digest: sha-256=:d435Qo+nKZ+gLcUHn7GQtQ72hiBVAgqoLsZnZPiTGPk=:

Figure 19: Empty Response with Digest

B.6. Client and Server Provide Full Representation Data​

The response contains two digest values using different algorithms.

For presentation purposes, the response body is displayed as a sequence of hex-encoded bytes because it contains non-printable characters.

NOTE: '' line wrapping per RFC 8792

PUT /items/123 HTTP/1.1
Host: foo.example
Content-Type: application/json
Accept-Encoding: br
Repr-Digest: \
  sha-256=:RK/0qy18MlBSVnWgjwz6lZEWjP/lF5HF9bvEF8FabDg==:

{"hello": "world"}

Figure 20: PUT Request with Digest

NOTE: '' line wrapping per RFC 8792

HTTP/1.1 200 OK
Content-Type: application/json
Content-Encoding: br
Content-Location: /items/123
Repr-Digest: \
  sha-256=:d435Qo+nKZ+gLcUHn7GQtQ72hiBVAgqoLsZnZPiTGPk=:,\
  sha-512=:db7fdBbgZMgX1Wb2MjA8zZj+rSNgfmDCEEXM8qLWfpfoNY0sCpHAzZbj\
  09X1/7HAb7Od5Qfto4QpuBsFbUO3dQ==:

8B 08 80 7B 22 68 65 6C 6C 6F
22 3A 20 22 77 6F 72 6C 64 22
7D 0A 03

Figure 21: Response with Digest of Encoded Content

B.7. POST Response Does Not Reference the Request URI​

The request Repr-Digest field-value is computed on the enclosed representation (see Section 3.1), which is the JSON object {"title": "New Title"} followed by an LF.

The representation enclosed in the response is a multiline JSON object followed by an LF. It refers to the resource identified by Content-Location (see Section 6.4.2 of [HTTP]); thus, an application can use Repr-Digest in association with the resource referenced by Content-Location.

POST /books HTTP/1.1
Host: foo.example
Content-Type: application/json
Accept: application/json
Accept-Encoding: identity
Repr-Digest: sha-256=:mEkdbO7Srd9LIOegftO0aBX+VPTVz7/CSHes2Z27gc4=:

{"title": "New Title"}

Figure 22: POST Request with Digest

HTTP/1.1 201 Created
Content-Type: application/json
Content-Location: /books/123
Location: /books/123
Repr-Digest: sha-256=:uVSlinTTdQUwm2On4k8TJUikGN1bf/Ds8WPX4oe0h9I=:

{
  "id": "123",
  "title": "New Title"
}

Figure 23: Response with Digest of Resource

B.8. POST Response Describes the Request Status​

The request Repr-Digest field-value is computed on the enclosed representation (see Section 3.1), which is the JSON object {"title": "New Title"} followed by an LF.

The representation enclosed in the response describes the status of the request, so Repr-Digest is computed on that enclosed representation. It is a multiline JSON object followed by an LF.

Response Repr-Digest has no explicit relation with the resource referenced by Location.

POST /books HTTP/1.1
Host: foo.example
Content-Type: application/json
Accept: application/json
Accept-Encoding: identity
Repr-Digest: sha-256=:mEkdbO7Srd9LIOegftO0aBX+VPTVz7/CSHes2Z27gc4=:

{"title": "New Title"}

Figure 24: POST Request with Digest

HTTP/1.1 201 Created
Content-Type: application/json
Repr-Digest: sha-256=:yXIGDTN5VrfoyisKlXgRKUHHMs35SNtyC3szSz1dbO8=:
Location: /books/123

{
  "status": "created",
  "id": "123",
  "ts": 1569327729,
  "instance": "/books/123"
}

Figure 25: Response with Digest of Representation

B.9. Digest with PATCH​

This case is analogous to a POST request where the target resource reflects the target URI.

The PATCH request uses the application/merge-patch+json media type defined in [RFC7396]. Repr-Digest is calculated on the content that corresponds to the patch document and is the JSON object {"title": "New Title"} followed by an LF.

The response Repr-Digest field-value is computed on the complete representation of the patched resource. It is a multiline JSON object followed by an LF.

PATCH /books/123 HTTP/1.1
Host: foo.example
Content-Type: application/merge-patch+json
Accept: application/json
Accept-Encoding: identity
Repr-Digest: sha-256=:mEkdbO7Srd9LIOegftO0aBX+VPTVz7/CSHes2Z27gc4=:

{"title": "New Title"}

Figure 26: PATCH Request with Digest

HTTP/1.1 200 OK
Content-Type: application/json
Repr-Digest: sha-256=:uVSlinTTdQUwm2On4k8TJUikGN1bf/Ds8WPX4oe0h9I=:

{
  "id": "123",
  "title": "New Title"
}

Figure 27: Response with Digest of Representation

Note that a 204 No Content response without content, but with the same Repr-Digest field-value, would have been legitimate too. In that case, Content-Digest would have been computed on an empty content.

B.10. Error Responses​

In error responses, the representation data does not necessarily refer to the target resource. Instead, it refers to the representation of the error.

In the following example, a client sends the same request from Figure 26 to patch the resource located at /books/123. However, the resource does not exist and the server generates a 404 response with a body that describes the error in accordance with [RFC9457].

The response Repr-Digest field-value is computed on this enclosed representation. It is a multiline JSON object followed by an LF.

HTTP/1.1 404 Not Found
Content-Type: application/problem+json
Repr-Digest: sha-256=:EXB0S2VF2H7ijkAVJkH1Sm0pBho0iDZcvVUHHXTTZSA=:

{
  "title": "Not Found",
  "detail": "Cannot PATCH a non-existent resource",
  "status": 404
}

Figure 28: Response with Digest of Error Representation

B.11. Use with Trailer Fields and Transfer Coding​

An origin server sends Repr-Digest as trailer field, so it can calculate digest-value while streaming content and thus mitigate resource consumption. The Repr-Digest field-value is the same as in Appendix B.1 because Repr-Digest is designed to be independent of the use of one or more transfer codings (see Section 3).

In the response content below, the string "\r\n" represents the CRLF bytes.

GET /items/123 HTTP/1.1
Host: foo.example

Figure 29: GET Request

NOTE: '' line wrapping per RFC 8792

HTTP/1.1 200 OK
Content-Type: application/json
Transfer-Encoding: chunked
Trailer: Repr-Digest

8\r\n
{"hello"\r\n
8\r\n
: "world\r\n
3\r\n
"}\n\r\n
0\r\n
Repr-Digest: \
  sha-256=:RK/0qy18MlBSVnWgjwz6lZEWjP/lF5HF9bvEF8FabDg==:\r\n

Figure 30: Chunked Response with Digest

Last updated on