Transitioning from API v1.0 to API v2.0

Article
01/25/2024

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.

Share via