Modifier

Partager via

Transitioning from API v1.0 to API v2.0

  • Article

Business Central API v2.0 includes some major changes from v1.0 to improve the experience. This article describes these changes and how to transition from v1.0 to v2.0.

Schema version

API v2.0 schema version is always set to 2.0 to get the latest features in the Business Central OData stack.

Key fields

In v1.0, following resources didn’t use the SystemId as the primary key. Instead they used non-GUID keys or multipart keys.

  • attachments
  • cashFlowStatement
  • customerSale
  • defaultDimensions
  • dimensionLines
  • generalLedgerEntries
  • generalLedgerEntryAttachments
  • incomeStatement
  • purchaseInvoiceLines
  • retainedEarningsStatement
  • salesCreditMemoLines
  • salesInvoiceLines
  • salesOrderLines
  • salesQuoteLines
  • trialBalance
  • vendorPurchase

All multipart keys and non-GUID in v2.0 are replaced with unique GUID keys. API v2.0 entities can be retrieved with the SystemId. SystemId is immutable, platform-enforced, and indexed. This change improves auditing and API reading performance. It's also possible to create a new record and provide the SystemId in API v2.0.

Nested objects

In API v1.0, some properties had complex types. These properties defined an ODataEDMType Property that can be assigned following values.

  • POSTALADDRESS
  • Collection(DIMENSION)
  • ITEM-UOM
  • DOCUMENTLINEOBJECTDETAILS

Complex properties allowed returning nested JSON object in the API response. In API v2.0, all complex properties are replaced with first-level properties or navigation properties. This change improves API performance significantly since complex fields were calculated in the runtime and added more compute time.

The change from complex property to first-level property can be seen in customer resource type. In API v1.0, property address used POSTALADDRESS.

Here's an example of the response from API v1.0 customer resource. The address property can be seen as a complex property.

Note

The response objects shown here might be truncated for brevity. All of the properties will be returned from an actual call.

{
  "id": "id-value",
  "number": "10000",
  "displayName": "Coho Winery",
  "type": "Company",
  "address": {
    "street": "192 Market Square",
    "city": "Atlanta",
    "state": "GA",
    "countryLetterCode": "US",
    "postalCode": "31772"
  }
}

Here's the first-level property replacement of the address property in an example response from API v2.0 customer resource.

{
    "id": "id-value",
    "number": "10000",
    "displayName": "Adatum Corporation",
    "type": "Company",
    "addressLine1": "192 Market Square",
    "addressLine2": "",
    "city": "Atlanta",
    "state": "GA",
    "country": "US",
    "postalCode": "31772",
}

The change from complex property to navigational property can be seen in item resource type. In API v1.0, property baseUnitOfMeasure used ITEM-UOM.

Here's an example of the response from API v1.0 item resource. The baseUnitOfMeasure property can be seen as a complex property.

Note

The response objects shown here may be truncated for brevity. All of the properties will be returned from an actual call.

{
  "id": "id-value",
  "number": "1896-S",
  "displayName": "ATHENS Desk",
  "baseUnitOfMeasure": {
    "unitCode": "PCS",
    "unitName": "Piece",
    "symbol": "",
    "unitConversion": null
  }
}

There's no first-level property replacement of the baseUnitOfMeasure property in an example response from API v2.0 item resource. Instead, the new navigation property replacement unitOfMeasure represents data from related unitOfMesure resource and might be optionally included in the response object. Navigation properties are included in the response object by $expand OData parameter.

GET businesscentralPrefix/companies({id})/items({id})?$expand=unitOfMeasure

{
  "id": "id-value",
  "number": "1896-S",
  "displayName": "ATHENS Desk",
  "unitOfMeasure": {
    "id": "id-value",
    "code": "PCS",
    "displayName": "Piece",
    "internationalStandardCode": "EA",
    "symbol": ""
  }
}

All navigation properties are documented in API (v2.0) Documentation.

Relationship multiplicities

In API v1.0, API sub pages (navigational properties) were always considered as collections. Therefore, all navigational properties returned a JSON array. In API v2.0 following properties are marked as Multiplicity = ZeroOrOne meaning a one-to-one relation. These properties return a JSON object in API v2.0.

Resource Property
contacts contact
contactInformation contact
customer agedAccountsReceivable
customer customerFinancialDetails
customer picture
employee picture
item generalProductPostingGroup
item inventoryPostingGroup
item picture
item unitOfMeasure
purchaseInvoiceLine location
purchaseInvoice pdfDocument
purchaseOrderLine location
salesCreditMemoLine location
salesCreditMemo pdfDocument
salesInvoiceLine location
salesInvoice pdfDocument
salesOrderLine location
salesQuoteLine location
salesQuote pdfDocument
vendor agedAccountsPayable
vendor picture

Enums

All properties that were of type option in API v1.0 are converted into enums for API v2.0. These properties were previously exposed as strings, instead now they're strongly typed. Enum values can be accessed from the metadata endpoint, also enum captions can be accessed from the entityDefinitions endpoint.

This change allows integration utilizing Business Central API v2.0 to determine available values for enum properties, for example displaying dropdown values to the end user.

API (v2.0) documentation
API (v1.0) documentation
Tips for working with the APIs
Enabling the APIs for Dynamics 365 Business Central
Developing a custom API