Prepare text for HTTP directorate review

[paulhowardarm]

Summary

We will be offering up this draft for HTTP directorate review due to the inclusion of HTTP-based protocol. This request is to prep the text for such a review.

Details

We should comb the text for deviations from the style guide, and apply any obvious fixes before submitting for more in-depth review. Style guide is here.

[paulhowardarm]

Analysis below from an AI tool, which was instructed to ingest the style guide and judge the published CoSERV draft version 05. The results below are verbatim as the AI tool reported, and are offered here in case they are useful:-

I reviewed the HTTPWG editorial style guide and the latest published CoSERV draft version -05, with particular attention to Section 6. Overall, the draft is reasonably well aligned in substance, especially in its use of HTTP examples, use of reason phrases with status codes in many places, and inclusion of concrete request/response examples with line-wrapping notes for long lines. Section 6 is clearly written and already follows a number of HTTP-documentation conventions.

The main gaps are editorial consistency issues rather than protocol-design problems. The strongest mismatches with the style guide are the repeated use of “body” / “response body” where the guide prefers “content”, a few places where methods are described as “HTTP GET verb” or “HTTP GET method” instead of simply GET or HTTP method GET, and several places where status-code prose uses the less-preferred form “HTTP 200 (OK) status code” rather than “the 200 (OK) status code.” These issues are concentrated in Section 6 and its examples/caching text.

I would characterize the draft as good alignment with moderate editorial cleanup needed. It does not look stylistically out of family with HTTP documentation, but it would benefit from a polishing pass to match the HTTPWG house style more closely. One caveat: the style guide recommends labeling HTTP examples with the http-message type in the source markdown; that is not verifiable from the published HTML alone, so I have not treated that as a confirmed defect. The published draft does, however, show that the examples are in HTTP/1.1 format and already use RFC 8792 line-wrapping notices, which is directionally aligned.

Recommended edits

Replace “body” / “response body” / “contents of bodies” with “content” throughout Section 6 and example captions.

Examples:

“The response body can be formatted…” → “The response content can be formatted…”

“the response body MUST contain exactly one discovery document…” → “the response content MUST contain exactly one discovery document…”

“Endpoint implementations MUST respond with an HTTP status code and response body…” → “…with a status code and response content…”

“In the following examples, the contents of bodies…” → “…the example content…”

This is the clearest stylistic mismatch with the guide.

In Section 6.1, change “The HTTP GET verb is then used…” to “The GET method is then used…” or “A GET request is then used…”.

The guide prefers bare method names and specifically says not to quote or emphasize them.

In Section 6.1.1, change “available via an HTTP GET method” to “available via GET” or “available using the GET method.”

Same issue: simplify method naming to match HTTPWG style.

In Section 6.1.2, change “The HTTP method is GET.” to “The method is GET.” or “Use the GET method.”

This is a direct match for the guide’s stated preference.

Rewrite status-code prose to the preferred form “the 200 (OK) status code” / “the 406 (Not Acceptable) status code” rather than “an HTTP 200 (OK) status code”.

Example:

“the implementation MUST respond with an HTTP 200 (OK) status code” → “the implementation MUST respond with the 200 (OK) status code”

This is small, but it is exactly the style guide’s recommendation.

Consider revising subsection headings such as “Successful Transaction (200)”, “Failure to Validate Query (400)”, and “Failure to Negotiate Profile (406)” to include the reason phrase:

“Successful Transaction (200 (OK))”

“Failure to Validate Query (400 (Bad Request))”

“Failure to Negotiate Profile (406 (Not Acceptable))”

The guide’s preferred status-code form includes both code and reason phrase. This is not mandatory for headings, but it would improve consistency.

Refer to the Accept field more consistently as the Accept header field after first mention.

Current wording mixes forms like “HTTP Accept header”.

A more HTTPWG-like phrasing would be: “the Accept header field”.

The style guide prefers explicit field terminology and avoids repeated quotation after first mention.

Refer to Cache-Control consistently as the Cache-Control header field, and avoid switching between prose such as “cache-control headers”, backticked examples, and generic “cache directives” without naming the field.

This is a softer recommendation, but it would improve consistency with the guide’s field-name conventions.

In Section 6.1.3.1, change “contained within the CoSERV result set payload” to “contained in the CoSERV result set content” or simply “contained in the CoSERV result set.”

This aligns both with the guide’s “content” preference and with the fact that this sentence is in the HTTP binding section, not the COSE structure definition.

Consider using named references for core HTTP specifications in future source edits, especially for HTTP semantics/caching citations, rather than generic citations like [STD98] in prose.

The guide says named references are preferred for core specifications like HTTP.

This is a source-level/style cleanup, not a correctness issue.

Where source markdown is next edited, verify that the HTTP examples are marked as http-message blocks.

I cannot confirm this from the published HTML, so I would treat it as a check item rather than a definite edit. The rendered examples themselves are otherwise well structured and already use HTTP/1.1 formatting and RFC 8792 wrapping notes.

[paulhowardarm]

I've checked the markdown source, and it is correctly using the http-message tagging already, so we can disregard those concerns from the AI report above.

[thomas-fossati]

We need to ensure that our requirements regarding error responses are clear.

For example, the use of concise problem details is suggested in the examples, but not mandated, even though it should be.

We should also discuss the use of HTTP-layer authentication mechanisms.

[thomas-fossati]

An item that could be tackled here is the one raised in #81 (comment), i.e., documenting the use of Cache-Control: no-cache in a request to revalidate the request with the origin CoSERV service.

[thomas-fossati]

A few other security-related topics that are in scope with the HTTP API binding:

1. API authentication. Server-side authentication is likely mandatory. Client-side authentication may be useful in some cases, for example, for authorisation or to prevent DoS attacks.
2. Deployments that offer a public-facing endpoint should seek DDoS protection.
3. Rate-limiting is common in this kind of energy-hungry service. If so, we might want to document status code 429 (Too Many Requests) alongside the other error responses.