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

Refine API part multiplicity guidance

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

Copilot-Session: 1c37924e-9749-4e63-9d58-bd73d659f736
This commit is contained in:
Jesper Schulz-Wedde 2026-07-14 12:35:52 +02:00
parent eb15b295ea
commit 1d02f9dccf
2 changed files with 6 additions and 6 deletions
Download patch file Download diff file Expand all files Collapse all files

8
microsoft/knowledge/web-services/link-api-parts-on-systemid-and-set-multiplicity.md
View file

@ -11,20 +11,20 @@ application-area: [all]
## Description
An API page part creates an OData navigation property and, for a 1:N relationship, enables deep insert of child entities. When a custom parent API is keyed by its immutable `SystemId`, its child should carry a related GUID foreign key so the navigation constraint uses that same stable external identity. Omitted `Multiplicity` validly defaults to 1:N collection metadata; set `ZeroOrOne` explicitly only when the part is intended to expose a singleton.
`Multiplicity` is available from runtime 6.3 (Business Central 17.3) and defaults an API page part to a 1:N collection. The multiplicity-specific guidance therefore does not apply to BC 17.0 through 17.2. An API page part creates an OData navigation property and, for collection multiplicity, enables deep insert of child entities. When a custom parent API is keyed by its immutable `SystemId`, its child should carry a related GUID foreign key so the navigation constraint uses that same stable external identity. `Multiplicity` controls whether metadata exposes an object (`ZeroOrOne`) or a collection (`Many`).
## Best Practice
Define the child foreign key as `Guid` with a `TableRelation` to the parent table's `SystemId`, then use `SubPageLink = "<Parent Id>" = Field(SystemId)` on the parent API page. For a child collection and deep insert, either use the documented default or declare `Multiplicity = Many`; for singleton metadata, declare `Multiplicity = ZeroOrOne`.
Define the child foreign key as `Guid` with a `TableRelation` to the parent table's `SystemId`, then use `SubPageLink = "<Parent Id>" = Field(SystemId)` on the parent API page. A child collection may omit `Multiplicity` and rely on the default 1:N relationship, or declare `Multiplicity = Many` explicitly. Set `Multiplicity = ZeroOrOne` when the intended navigation metadata is a singleton.
See sample: `link-api-parts-on-systemid-and-set-multiplicity.good.al`.
## Anti Pattern
On a parent API with `ODataKeyFields = SystemId`, linking a child business field such as `"Order No."` to the parent's `"No."` creates a second identity scheme for navigation instead of using the contract's stable GUID. A separate defect is an explicit multiplicity that contradicts the intended shape, such as `ZeroOrOne` on an order-lines collection or `Many` on a singleton. Omission alone is valid for the default 1:N collection.
On a parent API with `ODataKeyFields = SystemId`, linking a child business field such as `"Order No."` to the parent's `"No."` creates a second identity scheme for navigation instead of using the contract's stable GUID. A separate defect is an explicit `Multiplicity` that conflicts with the intended shape, such as `ZeroOrOne` on an order-lines collection or `Many` on a singleton. Do not treat omission alone as a defect: it is valid for a collection because the default is 1:N, while an intended singleton must explicitly use `Multiplicity = ZeroOrOne`.
See sample: `link-api-parts-on-systemid-and-set-multiplicity.bad.al`.
## Source
[Developing a custom API](https://learn.microsoft.com/dynamics365/business-central/dev-itpro/developer/devenv-develop-custom-api) and [Multiplicity property](https://learn.microsoft.com/dynamics365/business-central/dev-itpro/developer/properties/devenv-multiplicity-property). `Multiplicity` is available from runtime 6.3, shipped with Business Central 17.3; BC17 consumers therefore need update 17.3 or later.
[Developing a custom API](https://learn.microsoft.com/dynamics365/business-central/dev-itpro/developer/devenv-develop-custom-api) and [Multiplicity property](https://learn.microsoft.com/dynamics365/business-central/dev-itpro/developer/properties/devenv-multiplicity-property).