Microsoft/bcquality
1
0
Fork 0
mirror of https://github.com/microsoft/BCQuality.git synced 2026-10-05 14:46:55 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions 4
bcquality/microsoft/knowledge/web-services/expose-systemid-as-the-api-key.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

2.1 KiB
Raw Blame History

bc-version domain keywords technologies countries application-area
all
web-services
api-page
odatakeyfields
systemid
stable-key
guid
business-key
editable-false
al
w1
all

Address API records by SystemId, not by a renamable business key

Description

Every BC table carries a SystemId — an immutable GUID assigned at insert and never reused. API consumers must address a record through a key that does not change, otherwise a previously stored URL or @odata.id reference breaks the moment a user renames the underlying business key. The convention is to set ODataKeyFields = SystemId on the API page and expose the GUID as a non-editable field(id; Rec.SystemId). An LLM left to its own devices often reaches for the human-readable primary key (a customer No., an item code) as the OData key, because that is what a developer types when filtering in AL. That choice is wrong for an external contract: business keys are renamable and the API caller's stored references would dangle. This file is remedial because the correct key (SystemId) is rarely the one the model would pick by analogy with ordinary AL code.

Best Practice

Set ODataKeyFields = SystemId so OData routes records by the stable GUID, and expose it as field(id; Rec.SystemId) marked Editable = false. Clients then address a record at .../customers(<guid>), an identity that survives any rename of the business key. Keep the business key (for example No.) as an ordinary exposed field, not as the OData key.

See sample: expose-systemid-as-the-api-key.good.al.

Anti Pattern

Setting ODataKeyFields = "No." so the endpoint addresses records by a renamable business field. As soon as a user changes that No., every external reference built on the old value points at nothing, silently breaking integrations. The detection signal: ODataKeyFields set to a business field rather than SystemId, or an API page that exposes no id field bound to Rec.SystemId.

See sample: expose-systemid-as-the-api-key.bad.al.