shift-org / shift-org/shift-docs
API - send/receive API version as header
Nobody has claimed this yet.
- Dominant language
- JavaScript
- Stars
- 30
- Forks
- 25
- Avg merge
- 9m
- Merged PRs (30d)
- 1
Description
The API should include the version number as a header in responses, e.g.
API-Version: 3
(Major version number only?)
Clients would also be encouraged (though not required) to include the version they're using in requests. If the client doesn't specify, the server would assume the latest version. In the future we may rev the version and introduce breaking changes, so clients should send the version they're expecting to ensure a predictable response.
As a proof of concept for handling different versions, we could check for v1 or v2 requests and reject those. (There should be no real requests for those versions, because those version numbers were defined post-hoc well after we were already on v3.) Error status code could be 400, or possibly 406 (Not Acceptable).
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reading the version changelog in docs/CALENDAR_API.md. Clarify whether requests and responses use major versions, which status code applies to unsupported versions, and whether the server defaults to the latest version. Done means the agreed version-negotiation behavior is documented and implemented with a proof of concept for v1 and v2.
Written by the indexing model from the issue text.
Assessment
- Domain
- api, backend-api-design
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100