Microsoft/bcquality
1
0
Fork 0
mirror of https://github.com/microsoft/BCQuality.git synced 2026-10-05 06:36:55 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions
bcquality/microsoft/knowledge/web-services/version-apis-by-adding-not-mutating-published-versions.md
Jesper Schulz-Wedde 2b5550c346
Some checks failed
Validate knowledge index / validate-index (push) Has been cancelled
Details
Validate AL review fixtures / validate-review-fixtures (push) Has been cancelled
Details
Validate frontmatter and structure / validate (push) Has been cancelled
Details
Improve partner onboarding and documentation navigation (#174) 
Lead with a complete plugin quick start and add task-oriented usage, troubleshooting, customization, and contribution guides. Preserve the broader plugin framing, correct conflicting contract guidance, support Agents folder reviews, and align repository validation. Convert existing sample references to clickable links without changing knowledge rules.

Co-authored-by: Jesper Schulz-Wedde <jesper.schulzwedde@microsoft.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
2026-09-09 17:31:03 +02:00

1.7 KiB
Raw Blame History

bc-version domain keywords technologies countries application-area
all
web-services
api-page
apiversion
versioning
published-contract
breaking-change
backward-compatibility
al
w1
all

Version changed API shapes with a new page object

Description

Once an API version is published, external clients depend on its exact shape — entity names, fields, keys, and behavior — as a stable contract. APIVersion can list several versions on one API page, but every listed route is generated from that same page object and therefore exposes the same shape. Adding 'v2.0' to a page and then changing its fields changes what both v1.0 and v2.0 serve. To preserve the v1 shape while introducing a different v2 shape, keep the v1 page unchanged and create a separate page object for v2.

Best Practice

Keep the existing page object and its APIVersion = 'v1.0' contract unchanged. Copy the page to a new object ID, set that object's APIVersion = 'v2.0', and make the v2-only shape changes there. A multi-value APIVersion list is appropriate only when the exact same page shape is supported under each listed version.

See sample: version-apis-by-adding-not-mutating-published-versions.good.al.

Anti Pattern

Editing the published v1.0 page in place breaks its clients. So does adding v2.0 to that same page and assuming subsequent field changes apply only to v2: both routes use one object shape. The detection signal is a breaking shape change without a separate API page object retaining the old version.

See sample: version-apis-by-adding-not-mutating-published-versions.bad.al.