microsoft / microsoft/api-guidelines

Clarify guidance for returning resources across api-versions

Open
#393 1 comment 0 reactions 0 assignees View on GitHub

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:

  1. In service v1, there is a resource Foo with one property Bar, and operations to GET and PUT Foo.
  2. 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.