Microsoft/bcquality
1
0
Fork 0
mirror of https://github.com/microsoft/BCQuality.git synced 2026-08-07 01:46:53 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

Trim web-services domain to 6 non-duplicative articles

Browse source 
Drop API entity-naming/camelCase and DelayedInsert articles (owned by the style domain). Reframe the committed-data and API-versioning articles to stay strictly within the endpoint design/behavior lane, and update the leaf skill's worklist tokens and Output example accordingly.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
Jesper Schulz-Wedde 2026-06-24 12:47:28 +02:00
parent 2da72e782a
commit 94c371dd90
9 changed files with 8 additions and 199 deletions
Download patch file Download diff file Expand all files Collapse all files

2
microsoft/knowledge/web-services/version-apis-by-adding-not-mutating-published-versions.md
View file

@ -11,7 +11,7 @@ application-area: [all]
## Description
Once an API version is published, external clients depend on its exact shape — the entity name, the set of exposed fields, the key. Changing any of that on the published version is a breaking change delivered silently: existing integrations that worked yesterday fail today with no warning. AL supports versioning directly because `APIVersion` accepts a *list* of versions on the same page. The correct way to evolve a published API is to add a new version (`'v2.0'`) alongside the existing one (`'v1.0'`) so both contracts are served, letting clients migrate on their own schedule. LLMs tend to "fix" an API by editing the live version in place, because in ordinary code you just change what's wrong; this file is remedial because a published API contract is immutable in a way ordinary internal code is not. This is API-specific versioning and complements, without duplicating, the general breaking-changes domain.
Once an API version is published, external clients depend on its exact shape — the entity name, the set of exposed fields, the key — as a frozen contract. Changing any of that on the already-published version is a breaking change delivered silently: integrations that worked yesterday fail today with no warning. The platform gives you a clean way to evolve without breaking anyone, because `APIVersion` accepts a *list* of versions on one page. The correct way to change a published API is to add the new version (`'v2.0'`) alongside the existing one (`'v1.0'`) — or publish a new API page for it — so both contracts are served side by side and clients migrate on their own schedule. LLMs tend to "fix" an API by editing the live version in place, because in ordinary code you just change what's wrong; this file is remedial because a published API version is an immutable contract in a way ordinary internal code is not.
## Best Practice