API Versioning
Nobody has claimed this yet.
Assessment
- Difficulty
- 5/5
- Estimated time
- Over a week
- Newbie friendliness
- 25/100
- Issue type
- Documentation
- Clarity
- Mostly clear
- Activity status
- Stale
- Domain
- api, backend-api-design, documentation
Research direction
Start with the API Lifecycle Management section and its RFC4627 reference, then review the established NRPP and BC Wildfire REST API versioning strategies mentioned in the issue. Done means the guidelines accurately explain an API versioning strategy that covers broader API changes without relying on an unsupported media-type interpretation.
Written by the indexing model from the issue text.
Description
The section on API Lifecycle Management prescribes identifying a version number in the mime type of a requests ACCEPT header and references RFC4627 as an endorsement of this practice.
The RFC4627 does not at all endorse using the version component of a mime type to indicate an API version. It is specific to indicating the version of a JSON structure. It is possible for a single version of an API to support many different representations of the same resource.
A new version of an API can include changes other than the addition or deprecation of supported resource structures. Specific examples being new behavior in existing interfaces, new workflows, new endpoints, deprecated endpoints, new SLAs, etc... The API Guidelines should provide a versioning strategy that addresses API changes; the mime type versioning does not.
(We have an established API versioning strategy for the NRPP and BC Wildfire Rest APIs that uses a separate HTTP Header to indicate the desired version of the API.)
Also many of the frameworks that we use to build our REST services, including Jersey, Spring, and CFX do not support custom mine types out of the box and require considerable configuration to provide custom handlers to support the serialization of the custom types. The frameworks support application\json and application\xml out of the box with no additional effort.
As standard tools do not know what to do with the custom mime types it will also be more difficult for new clients to consume the APIs that use a mime type versioning strategy.
- Dominant language
- No language data
- Stars
- 34
- Forks
- 10
- PR merge metrics
- No merged PRs in 30d
Getting set up
- No Dockerfile or Docker Compose file
- No pull request template
- Read the contributing guide
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.
More from bcgov/api-guidelines
-
Difficulty 1/5 Under an hour Newbie friendliness 72/100
bcgov/api-guidelines#34 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 25/100
bcgov/api-guidelines#33 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 55/100
bcgov/api-guidelines#32 ·
-
Difficulty 3/5 1-2 days Newbie friendliness 45/100
bcgov/api-guidelines#31 ·
-
It's Been a While Since This Repository has Been UpdatedMay be free again @jeff-card claimed this 1558 days ago, and no pull request is open. Open
bcgov/api-guidelines#28 · 3 comments · 2 assignees ·
All issues in bcgov/api-guidelines
Similar issues
-
Add an EPUB parserOpenarea: core good first issue
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
openapi/gknowledge#21 ·
-
get() for StrEnumPossibly taken @FeJo5952 claimed this today. Opengood first issue
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
collective/icalendar#1921 · 1 comment ·
Maintainers usually reply within 1 day
-
agent-butler-finding agent-research-recommend bug ready-for-agent
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
jordansmall/spindrift#5278 · 1 comment ·
Maintainers usually reply within 1 day
-
Improvement Python Spans
Difficulty 2/5 1-3 hours Newbie friendliness 62/100
getsentry/sentry-python#7990 · 1 comment ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
alphagov/notifications-api#5004 ·
Maintainers usually reply within 2 days