Microsoft/bcquality
1
0
Fork 0
mirror of https://github.com/microsoft/BCQuality.git synced 2026-08-06 17:36:53 +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 5706959e4a
Fix lifecycle compatibility guidance (#93) 
* Fix lifecycle compatibility guidance

Correct high-confidence Business Central guidance and samples for upgrade tags, collectible errors, trigger semantics, obsoletion, events, interfaces, API contracts, and test transactions.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: e05a43e7-6448-4d67-9c73-798523f5d945

* Address guidance review findings

Gate SecretText guidance to BC23 and clarify that the collectible-error sample intentionally emits a message-only blocking aggregate.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: e05a43e7-6448-4d67-9c73-798523f5d945

---------

Co-authored-by: Jesper Schulz-Wedde <jesper.schulzwedde@microsoft.com>
2026-07-14 11:26:16 +02:00

1.6 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.