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

Correct API part multiplicity guidance

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

Copilot-Session: 02baffe8-0600-430d-81fa-a9993685e7cb
This commit is contained in:
Jesper Schulz-Wedde 2026-07-14 12:31:25 +02:00
parent cf55246ecf
commit eb15b295ea
4 changed files with 8 additions and 8 deletions
Download patch file Download diff file Expand all files Collapse all files

1
microsoft/knowledge/web-services/link-api-parts-on-systemid-and-set-multiplicity.bad.al
View file

@ -19,6 +19,7 @@ page 50353 "WS Order API Bad"
{
EntityName = 'orderLine';
EntitySetName = 'orderLines';
Multiplicity = ZeroOrOne;
SubPageLink = "Order No." = Field("No.");
}
}

1
microsoft/knowledge/web-services/link-api-parts-on-systemid-and-set-multiplicity.good.al
View file

@ -23,7 +23,6 @@ page 50350 "WS Order API"
{
EntityName = 'orderLine';
EntitySetName = 'orderLines';
Multiplicity = Many;
SubPageLink = "Order Id" = Field(SystemId);
}
part(summary; "WS Order Summary API")

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

@ -1,5 +1,5 @@
---
bc-version: [18..]
bc-version: [17..]
domain: web-services
keywords: [api-page, page-part, subpagelink, systemid, multiplicity, deep-insert, navigation-property]
technologies: [al]
@ -7,24 +7,24 @@ countries: [w1]
application-area: [all]
---
# Link API parts on SystemId and declare their multiplicity
# Link API parts on SystemId and choose the correct multiplicity
## Description
An API page part creates an OData navigation property and, for `Multiplicity = Many`, 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` also controls whether metadata exposes an object (`ZeroOrOne`) or a collection (`Many`), so declare it deliberately instead of relying on the default 1:N relationship.
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.
## 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. Set `Multiplicity = Many` for child collections and deep insert, or `Multiplicity = ZeroOrOne` for a singleton navigation property.
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`.
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."`, or omitting `Multiplicity` because the current default happens to produce a collection. The first creates a second identity scheme for navigation instead of using the contract's stable GUID; the second hides whether the contract intentionally exposes a singleton or 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 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.
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).
[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.