Section 3.7 Version Negotiation. closes #78 - #200
Open
saumier wants to merge 1 commit into
Open
Conversation
✅ Deploy Preview for reconciliation-api-specs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
fsteeg
reviewed
Jul 16, 2026
fsteeg
left a comment
fsteeg
left a comment
Member
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. |
Member
There was a problem hiding this comment.
To actually support multiple versions, to me it seem the service MUST check the header:
Suggested change
| 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 |
Member
There was a problem hiding this comment.
I find 'advertises' a bit confusing here. How about this:
Suggested change
| If a request explicitly advertises only unsupported reconciliation versions, services SHOULD return | |
| If a client explicitly requests only unsupported reconciliation versions, services SHOULD return |
Comment on lines
+572
to
+578
| <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> | ||
|
|
Member
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:
Suggested change
| <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> | |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.