microsoft / microsoft/api-guidelines
Clarify guidance for returning resources across api-versions
Nobody has claimed this yet.
- Dominant language
- No language data
- Stars
- 23.3k
- Forks
- 2.7k
- PR merge metrics
- No merged PRs in 30d
Description
For client development, it is important to know what a service will return in the following situation:
- In service v1, there is a resource Foo with one property Bar, and operations to GET and PUT Foo.
- In service version 2, an optional property Baz is added to Foo. Assuming the service holds a resource Foo { Bar='a', Baz='b' },
- GET Foo with api-version=v2 will return Foo { Bar='a', Baz='b' }
- GET Foo with api-version=v1 will return either:
A. Foo { Bar='a' } because Baz is unknown in api-version=v1 or
B. Foo { Bar='a', Baz='b' } because this represents the full resource
From conversations with @JeffreyRichter, I believe A is recommended, although from conversations with @tg-msft, I believe B is more common in practice.
Would it be possible to clarify what the guidance to services is in this case? Thanks!
Contributor 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.
Research direction
Start with the versioning scenario and the contrasting guidance described in the issue, then review the existing API guidance for returning resources across versions. Done means resolving whether behavior A or B is recommended and documenting that guidance clearly for services.
Written by the indexing model from the issue text.
Assessment
- Domain
- api
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100