Section 3.7 Version Negotiation. closes #78 - #200
Conversation
✅ Deploy Preview for reconciliation-api-specs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
fsteeg
left a comment
fsteeg
left a comment
There was a problem hiding this comment.
Thanks Gregory! Looks good overall, some inline suggestions below.
| <pre class="example nohighlight">Accept: application/reconciliation.v1+json</pre> | ||
| </p> | ||
| <p> | ||
| A service that supports multiple versions SHOULD inspect this header and serve the highest-priority compatible version. |
There was a problem hiding this comment.
To actually support multiple versions, to me it seem the service MUST check the header:
| A service that supports multiple versions SHOULD inspect this header and serve the highest-priority compatible version. | |
| A service that declares support for multiple versions in its manifest MUST inspect this header and serve the highest-priority compatible version. |
| Services SHOULD only apply fallback when no reconciliation-specific media type is supplied in <code>Accept</code>. | ||
| In that case, services SHOULD use a documented default version for unversioned requests, | ||
| such as their latest stable version. | ||
| If a request explicitly advertises only unsupported reconciliation versions, services SHOULD return |
There was a problem hiding this comment.
I find 'advertises' a bit confusing here. How about this:
| If a request explicitly advertises only unsupported reconciliation versions, services SHOULD return | |
| If a client explicitly requests only unsupported reconciliation versions, services SHOULD return |
| <p> | ||
| For debugging, services MAY also include an informational header such as: | ||
| <code>Reconciliation-Version: 1.0</code> | ||
| If provided, this header is informational only and MUST NOT override the negotiated | ||
| representation indicated by <code>Content-Type</code>. | ||
| </p> | ||
|
|
There was a problem hiding this comment.
Isn't this redundant? We already provide that info in the Content-Type and the Link headers, plus it's the only non-standard header here, and it adds ambiguity (which you clarify in the text). So from my point of view, this could be removed:
| <p> | |
| For debugging, services MAY also include an informational header such as: | |
| <code>Reconciliation-Version: 1.0</code> | |
| If provided, this header is informational only and MUST NOT override the negotiated | |
| representation indicated by <code>Content-Type</code>. | |
| </p> | |
There was a problem hiding this comment.
I tend to agree, we can just stick to the normative part.
wetneb
left a comment
wetneb
left a comment
There was a problem hiding this comment.
Thanks for working on this! I'm going to look into implementing this for the Wikibase recon service, with version 0.2 as the default (meaning, only offer support for 1.0 for clients which pass this Accept header).
| <p> | ||
| A service that supports multiple versions SHOULD inspect this header and serve the highest-priority compatible version. | ||
| Reconciliation-specific media types in <code>Accept</code> SHOULD take precedence over generic media types such as | ||
| <code>application/json</code>. Clients MAY use standard HTTP quality factors in <code>Accept</code> to express preference |
There was a problem hiding this comment.
Nice, I didn't know about this mechanism. I propose to link to the specs directly, for the reader's convenience:
| <code>application/json</code>. Clients MAY use standard HTTP quality factors in <code>Accept</code> to express preference | |
| <code>application/json</code>. Clients MAY use standard HTTP quality factors as defined in [[RFC9110]] to express preference |
| <p> | ||
| For debugging, services MAY also include an informational header such as: | ||
| <code>Reconciliation-Version: 1.0</code> | ||
| If provided, this header is informational only and MUST NOT override the negotiated | ||
| representation indicated by <code>Content-Type</code>. | ||
| </p> | ||
|
|
There was a problem hiding this comment.
I tend to agree, we can just stick to the normative part.
| Content-Type: application/reconciliation.v1+json | ||
| Vary: Accept | ||
| Link: <https://reconciliation-api.github.io/specs/1.0/>; rel="profile" | ||
| Reconciliation-Version: 1.0 |
There was a problem hiding this comment.
Per the above, I'd remove this header line.
3 participants
No description provided.