Before we even begin

You are our demo!

Before we even begin

Install the Expo client app…

…from your app store

{Connect app}²
Connect app

• Your choice
What
rd
Technology
• REST Development
• Any 3 party
app that uses • Web hooks
data from
Business
Central
Connect app

What Technology Development

• Any 3rd party • REST • Your choice

app that uses • Web hooks
data from
Business
Central
BOOOOOOOOOORING
UID: ntd2019
PWD: Antwerp.19
What are Custom APIs?
What are Custom APIs?

Can be accessed
Can be developed Included in Add-on
using specific Easy to create
by any Partner apps
endpoints
Custom API considerations
Microsoft makes sure all their APIs are consistent
Consistency of your APIs is your responsibility

Naming and schema

Versioning
• You must notprinciple
break • Include SystemId Consistent behavior
• Table relationships
conventions
existing versions • lastModifiedDateTime • Complex types
• Any breaking change • Always use camelCase • Insertion /
requires up-versioning modification behavior
• API layer does no
versioning validations
for you
Custom API considerations
Microsoft makes sure all their APIs are consistent
Consistency of your APIs is your responsibility

Naming and schema

Versioning principle • Include SystemId Consistent behavior
• Table relationships
conventions
• lastModifiedDateTime • Complex types
• You must not break
• Always use camelCase • Insertion /
existing versions
modification behavior
• Any breaking change
requires up-versioning
• API layer does no
versioning validations
for you
Custom API considerations
Microsoft makes sure all their APIs are consistent
Consistency of your APIs is your responsibility

Naming and schema

Versioning principle Consistent behavior
• Table relationships
conventions
• Complex types
• You must not break • Include SystemId • Insertion /
existing versions • lastModifiedDateTime modification behavior
• Any breaking change • Always use camelCase
requires up-versioning
• API layer does no
versioning validations
for you
Custom API considerations
Microsoft makes sure all their APIs are consistent
Consistency of your APIs is your responsibility

Naming and schema

Versioning principle Consistent behavior
conventions
• You must not break • Include SystemId • Table relationships
existing versions • lastModifiedDateTime • Complex types
• Any breaking change • Always use camelCase • Insertion /
requires up-versioning modification behavior
• API layer does no
versioning validations
for you
Developing Custom APIs
The basics
APIs are OData

OData web services can be built as:

Pages
Queries

APIs can be developed as:

Pages
Queries
API definition properties
Namespace properties define the endpoint hierarchy:
• Become a part of the endpoint URL APIPublisher = ‘waldo';
• These are case-insensitive! APIGroup = ‘killerApp';
APIVersion = ‘v1.0';
• Should use camelCase
 API definition properties
Namespace properties define the endpoint hierarchy:
• Become a part of the endpoint URL APIPublisher = ‘waldo';
• These are case-insensitive! APIGroup = ‘killerApp';
APIVersion = ‘v1.0';
• Should use camelCase

https://api.businesscentral.dynamics.com/v2.0/<tenant_id>/<sandboxname>/api/waldo/killerApp/v1.0
 API definition properties
Namespace properties define the endpoint hierarchy:
• Become a part of the endpoint URL APIPublisher = ‘waldo';
• These are case-insensitive! APIGroup = ‘killerApp';
APIVersion = ‘v1.0';
• Should use camelCase

Entity properties define the EDM (Entity Data Model)

• These are case-sensitive!
• Should use camelCase EntityName = ‘crime’;
EntitySetName = ‘crimes';
/companies(<company_id>)/

https://api.businesscentral.dynamics.com/v2.0/<tenant_id>/<sandboxname>/api/waldo/killerApp/v1.0
 API definition properties
Namespace properties define the endpoint hierarchy:
• Become a part of the endpoint URL APIPublisher = ‘waldo';
• These are case-insensitive! APIGroup = ‘killerApp';
APIVersion = ‘v1.0';
• Should use camelCase

Entity properties define the EDM (Entity Data Model)

• These are case-sensitive!
• Should use camelCase EntityName = ‘crime’;
EntitySetName = ‘crimes';

https://api.businesscentral.dynamics.com/v2.0/<tenant_id>/<sandboxname>/api/waldo/killerApp/v1.0/companies(<company_id>)/crimes
Table considerations
Every entity table must provide required API fields and functionality

Last Modified DateTime Primary key

SystemId
• A GUID field field • A DateTime • The considerations Field considerations
• Fields should follow
fieldfield SystemId can’t be
• Virtual field – you don’t • Must be modified on the primary key Business Central
have to create or every record • The SystemId is more naming conventions,
maintain it yourself – modification. durable than the and not use camelCase
but you have to put it primary key. or PascalCase. Caption
on the API page • The id field must Case must be used
survive a change of the instead.
primary key values
(renaming in AL
terminology).
Table considerations
Every entity table must provide required API fields and functionality

Last Modified DateTime Primary key

SystemId field • A DateTime • The considerations Field should
• Fields considerations
fieldfield SystemId can’t be follow
• Must be modified on the primary key Business Central
• A GUID field every record • The SystemId is more naming conventions,
• Virtual field – you don’t modification. durable than the and not use camelCase
have to create or primary key – it or PascalCase. Caption
maintain it yourself – survives the rename Case must be used
but you have to put it operation. instead.
on the API page
Table considerations
Every entity table must provide required API fields and functionality

Last Modified DateTime Primary key

SystemId field Field considerations
field • The considerations
SystemId can’t be • Fields should follow
the primary key Business Central
• A GUID field • A DateTime field naming conventions,
• The SystemId is more
• Virtual field – you don’t • Must be modified on durable than the and not use camelCase
have to create or every record primary key – it or PascalCase. Caption
maintain it yourself – modification. survives the rename Case must be used
but you have to put it operation. instead.
on the API page
Table considerations
Every entity table must provide required API fields and functionality

Last Modified DateTime Primary key

SystemId field Field considerations
field considerations • Fields should follow
Business Central
• A GUID field • A DateTime field • The SystemId can’t be naming conventions,
• Virtual field – you don’t • Must be modified on the primary key and not use camelCase
have to create or every record • The SystemId is more or PascalCase. Caption
maintain it yourself – modification. durable than the Case must be used
but you have to put it primary key – it instead.
on the API page survives the rename
operation.
Table considerations
Every entity table must provide required API fields and functionality

Last Modified DateTime Primary key

SystemId field Field considerations
field considerations
• A GUID field • A DateTime field • The SystemId can’t be • Fields should follow
• Virtual field – you don’t • Must be modified on the primary key Business Central
have to create or every record • The SystemId is more naming conventions,
maintain it yourself – modification. durable than the and not use camelCase
but you have to put it primary key – it or PascalCase. Caption
on the API page survives the rename Case must be used
operation. instead.
Page considerations
Every page must provide correct mapping of the entity table to REST
format and behavior

• All field names

Field must
names be set to
considerations • SystemId value must
Modify not be changed.
behavior
camelCase explicitly. • Primary key values can be changed
• Don’t set ApplicationArea. during a modification call, and this
• It’s the Name property of a page field needs to propagate as a Rename call
that defines how the field is in AL.
referenced in REST requests and
responses.
Page considerations
Every page must provide correct mapping of the entity table to REST
format and behavior

Field names considerations • SystemId value must

Modify not be changed.
behavior
• Primary key values can be changed
• All field names must be set to during a modification call, and this
camelCase explicitly. needs to propagate as a Rename call
• Don’t set ApplicationArea. in AL.
• It’s the Name property of a page field
that defines how the field is
referenced in REST requests and
responses.
Page considerations
Every page must provide correct mapping of the entity table to REST
format and behavior

Field names considerations Modify behavior

• All field names must be set to
camelCase explicitly.
• Don’t set ApplicationArea.
• It’s the Name property of a page field
that defines how the field is
referenced in REST requests and
responses.
• SystemId value must not be changed.
• Primary key values can be changed
during a modification call, and this
needs to propagate as a Rename call
in AL.
Useful resources
https://docs.microsoft.com/en-us/dynamics-nav/fin-graph/
https://docs.microsoft.com/en-us/dynamics365/business-central/dev-
itpro/developer/devenv-connect-apps-tips
Useful Tools
Rest Client
A VSCode Extension

Alows you to send HTTP

request and view the response

You can make the files part of

your app
PowerShell
Resetting the environment
Upload data
Quickly and efficiently Test APIs
Create a (manual) release pipeline to easily “reset” multiple environments
RequestBin
https://requestbin.com/

Online tool that creates a

subdomain which you can use to
test an API call.

Requests sent to any path on the

subdomain are forwarded to the
browser in real time.
OAuth
Two types of authentication
Dynamics 365 Business Central APIs support two types of authentication

• Base
theAuthentication OAuth 2.0 Authentication
Client uses credentials directly • Client uses a series of REST calls
• Performs actual authentication • Performs authentication delegation
• Lower security • Higher security
• Potentially exposes user’s secrets • Does not expose user’s secrets

• Works in on-prem, and cloud sandbox • Works in all environments when

and development environments. Azure AD authentication is used.

• Does not work in cloud production • Mandatory for all cloud production
environments. environments
Two types of authentication
Dynamics 365 Business Central APIs support two types of authentication

Base Authentication OAuth 2.0 Authentication

• Client uses a series of REST calls
• Performs authentication delegation
• Client uses the credentials directly
• Higher security
• Performs actual authentication
• Does not expose user’s secrets
• Lower security
• Potentially exposes user’s secrets
• Works in all environments when
Azure AD authentication is used.
• Works in on-prem, and cloud sandbox
and development environments.
• Mandatory for all cloud production
environments
• Does not work in cloud production
environments.
Two types of authentication
Dynamics 365 Business Central APIs support two types of authentication

Base Authentication OAuth 2.0 Authentication

• Client uses the credentials directly • Client uses a series of REST calls
• Performs actual authentication • Performs authentication delegation
• Lower security • Higher security
• Potentially exposes user’s secrets • Does not expose user’s secrets

• Works in on-prem, and cloud sandbox • Works in all environments when

and development environments. Azure AD authentication is used.

• Does not work in cloud production • Mandatory for all cloud production
environments. environments
What is OAuth 2.0
An open standard for access delegation, that allows users to grant
applications access to user information in other applications, without
exposing user credentials.

• User access isDelegation

delegated to an
application
• No user impersonation takes place
• User credentials are exchanged only
between the user and the
application that “owns” the
credentials (in case of Business
Central, it’s Azure Active Directory)
• Connecting application never has
access to user’s credentials
Token-based
• Connecting access
application only has • OAuth isWeb-based
REST-basedprotocol
access to an access token • Not applicable to non-HTTP
• Access tokens are short-lived, scenarios
issued to a specific client, and • All communication happens
cannot be reused through HTTP REST endpoints
• Tokens are issued by an
authorization server (Azure Active
Directory) with the approval of the
resource owner (Business Central)
What is OAuth 2.0
An open standard for access delegation, that allows users to grant
applications access to user information in other applications, without
exposing user credentials.

Delegation
• User access is delegated to an
application
• No user impersonation takes place
• User credentials are exchanged only
between the user and the
application that “owns” the
credentials (in case of Business
Central, it’s Azure Active Directory)
• Connecting application never has
access to user’s credentials
Token-based
• Connecting access
application only has • OAuth isWeb-based
REST-basedprotocol
access to an access token • Not applicable to non-HTTP
• Access tokens are short-lived, scenarios
issued to a specific client, and • All communication happens
cannot be reused through HTTP REST endpoints
• Tokens are issued by an
authorization server (Azure Active
Directory) with the approval of the
resource owner (Business Central)
What is OAuth 2.0
An open standard for access delegation, that allows users to grant
applications access to user information in other applications, without
exposing user credentials.

Delegation Token-based access • OAuth isWeb-based

• User access is delegated to an
application
• No user impersonation takes place
• User credentials are exchanged only
between the user and the
application that “owns” the
credentials (in case of Business
Central, it’s Azure Active Directory)
• Connecting application never has
access to user’s credentials
REST-basedprotocol
• Not applicable to non-HTTP
• Connecting application only has scenarios
access to an access token • All communication happens
• Access tokens are short-lived, through HTTP REST endpoints
issued to a specific client, and
cannot be reused
• Tokens are issued by an
authorization server (Azure Active
Directory) with the approval of the
resource owner (Business Central)
What is OAuth 2.0
An open standard for access delegation, that allows users to grant
applications access to user information in other applications, without
exposing user credentials.

Delegation Token-based access Web-based protocol

• User access is delegated to an • Connecting application only has • OAuth is REST-based

application
• No user impersonation takes place
• User credentials are exchanged only
between the user and the
application that “owns” the
credentials (in case of Business
Central, it’s Azure Active Directory)
• Connecting application never has
access to user’s credentials
access to an access token • Not applicable to non-HTTP
• Access tokens are short-lived, scenarios
issued to a specific client, and • All communication happens
cannot be reused through HTTP REST endpoints
• Tokens are issued by an
authorization server (Azure Active
Directory) with the approval of the
resource owner (Business Central)
OAuth 2.0 is not a single thing
• There are different flows in OAuth:

Authorization Code
Implicit Grant On-Behalf-Of
Grant

Resource Owner
Client Credentials Device Authorization
Password Credentials
Grant Grant
Grant
OAuth 2.0 is not a single thing
• There are different flows in OAuth:

Authorization Code
Grant Implicit Grant On-Behalf-Of

Third-party web and

native apps

Resource Owner
Client Credentials Device Authorization
Password Credentials
Grant Grant
Grant
OAuth 2.0 is not a single thing
• There are different flows in OAuth:

Authorization Code
Implicit Grant
Grant On-Behalf-Of

Third-party web and Single-page browser

native apps apps

Resource Owner
Client Credentials Device Authorization
Password Credentials
Grant Grant
Grant
OAuth 2.0 is not a single thing
• There are different flows in OAuth:

Authorization Code
Implicit Grant On-Behalf-Of
Grant

Third-party web and Single-page browser Pass-through multi-

native apps apps layer scenarios

Resource Owner
Client Credentials Device Authorization
Password Credentials
Grant Grant
Grant
OAuth 2.0 is not a single thing
• There are different flows in OAuth:

Authorization Code
Implicit Grant On-Behalf-Of
Grant

Third-party web and Single-page browser Pass-through multi-

native apps apps layer scenarios

Client Credentials Resource Owner

Grant Device Authorization
Password Credentials
Grant
Grant
Service-to-service
OAuth 2.0 is not a single thing
• There are different flows in OAuth:

Authorization Code
Implicit Grant On-Behalf-Of
Grant

Third-party web and Single-page browser Pass-through multi-

native apps apps layer scenarios

Client Credentials Device Authorization Resource Owner

Grant Grant Password Credentials
Grant
Service-to-service Smart devices and IoT
OAuth 2.0 is not a single thing
• There are different flows in OAuth:

Authorization Code
Implicit Grant On-Behalf-Of
Grant

Third-party web and Single-page browser Pass-through multi-

native apps apps layer scenarios

Resource Owner
Client Credentials Device Authorization
Password Credentials
Grant Grant
Grant

First-party apps with

Service-to-service Smart devices and IoT
high level of trust
Which flows are supported by Business Central
• OAuth is a feature of Azure Active Directory, not Business Central
• You can obtain tokens using all flows (tokens come from Azure)

• However (and a big one at that):

• Business Central rejects tokens when actual user cannot be identified
• This eliminates service-to-service calls
• Reason: license compliance

• Officially, according to Microsoft, these are supported:

• Authorization Code Grant
• Implicit Grant
Pssssst, don’t tell anyone

Resource Owner Password Credential Grant

works just fine.

Use this one for

service-to-service communication.
Selecting the right grant type

Who owns
the token?

Token Owner Machine User

Type of app Native Web Browser

First party or third party First party Third party First party Third party

Grant type Client

Credentials
Password
Credentials
Authorization
Code
Authorization
Code
Password
Credentials
Implicit
Authorization Code Grant Flow
• The most typical grant type
• The most comprehensive grant type
• Other grant types perform a subset of operations of Authorization Code
grant

• The grant type most familiar to users

Parties in OAuth 2.0 authorization code flow
OAuth 2.0 process has three parties

Resource owner Authorization server End-user application

The application that owns the resources An authority trusted by the resource Any application that requires access to the
the user has access to, and that the user owner, that will issue access tokens on resources.
wants to delegate access to. behalf of the resource owner.
How does OAuth 2.0 work in Business Central

6. Returns one-time, client-specific access token

5. Requests access token

(sends authorization code and client secret)
(client secret = app key)

2. Presents sign-in form

3. Provides credentials
Implementing OAuth 2.0 authentication
Implementing the client side of OAuth 2.0 protocol is your responsibility
Your OAuth 2.0 client must provide the described functionality

Redirect to /oauth2/authorize endpoint POST to /oauth2/token endpoint Use access token with Business Central

When user requests a Business Central Use HTTP POST method to send the Every REST request against Business Central
resource, redirect to the known endpoint. authorization code to the known endpoint API must include the token in the
Provide a callback URL that receives This is a regular REST invocation. authorization headers.
authorization code. Response contains the access token. When token expires, request refresh token.
UID: ntd2019
PWD: Antwerp.19
Get ready for the demo

Install the Expo client app…

…from your app store

UID: ntd2019
PWD: Antwerp.19
Architectural overview

Requests “like”
Tags item with
predictions
“likes” Stores
item images

Reads item information (API)

Automates
Subscribes to notifications (API) new item
creation
Sends Sends
prediction prediction
notifications notifications
Architectural Considerations in AL
Dependencies
 Introduce logging
Only responsible for Helpers for JSON and • Request/Response
• Duration
REST calls HTTP objects
• Timings
•…

Events
• OnBeforeSend Helper to call all http-
• OnAfterSend methods in the right
• ... order
Data Methods Objects Uses the REST
•Setup •Get TagsCreate •Image App
•Tags TagCreate Image •ImageReponse
•Create Image •Tag
•Create Tag Create
Image
•Create Image
•Create Image
•Predict
•Train
•...
The actual functionality
•New business logic
•New data model Uses CustomVision
•API
“Objectification”
Try to make it easy to work with the objects that needs to be sent to an
API call, and the objects you get back.

ImageClass CreateImageObject
HttpClient.Send ImageClass.SendMethod ImageObject.Send
WebResponse ImageResponseClass ImageResponse.GetId
Notifications
Don’t call us, we will call you
 Notifications
• Webhooks for Business Central APIs
• Interested parties can subscribe to data changes
• Business Central sends out notifications when changes occur

• Both standard and custom APIs expose the /subscriptions endpoint

https://api.businesscentral.dynamics.com/v2.0/<tenant_id>/<sandboxname>
/api/waldo/killerApp/v1.0
 Notifications
• Webhooks for Business Central APIs
• Interested parties can subscribe to data changes
• Business Central sends out notifications when changes occur

• Both standard and custom APIs expose the /subscriptions endpoint

https://api.businesscentral.dynamics.com/v2.0/<tenant_id>/<sandboxname>
/api/waldo/killerApp/v1.0/subscriptions
 Operations on the /subscriptions endpoint

• Retrieves GET
list of existing • Creates aPOST
new • Renews PATCH
an existing • DeletesDELETE
an existing
subscriptions subscription subscription subscription
 Operations on the /subscriptions endpoint

GET • Creates aPOST

new • Renews PATCH
an existing • DeletesDELETE
an existing
subscription subscription subscription
• Retrieves list of existing
subscriptions
 Operations on the /subscriptions endpoint

GET POST • Renews PATCH

an existing • DeletesDELETE
an existing
subscription subscription
• Retrieves list of existing • Creates a new
subscriptions subscription
 Operations on the /subscriptions endpoint

GET POST PATCH • DeletesDELETE

an existing
subscription
• Retrieves list of existing • Creates a new • Renews an existing
subscriptions subscription subscription
 Operations on the /subscriptions endpoint

GET POST PATCH DELETE

• Retrieves list of existing • Creates a new • Renews an existing • Deletes an existing

subscriptions subscription subscription subscription
Parties involved in subscription

Business Central End-user application

Provides subscription endpoints. Application that requires notifications

Parties involved in subscription

Business Central Notification dispatcher End-user application

Provides subscription endpoints. A middleware component needed in case Application that requires notifications
the end-user application is a native
application or a single-page browser
application.
Create a new subscription
• Send a POST request to the /subscribe endpoint
• Handshake occurs

• clientState a random string known only to the subscribing party

• notificationUrl URL that Business Central calls to confirm the subscription
• resource API entity to subscribe to
Create a new subscription

• clientSecret a random string known only to the subscribing party

• notificationUrl URL that Business Central calls to confirm the subscription
• resource API entity to subscribe to
• Handshake occurs

Sends
Callsa the
200 OK
response
notificationUrl
notificationUrl
Echoes back the
Passes
validationToken
clientSecret and
validationToken
Receiving notifications
• Business Central automatically sends notifications to notificationUrl

• Changes are accumulated in 30-second chunks

• When the first change occurs, a timeout is created
• Any change happening within the next 30 seconds is noted
• After timeout elapses, all noted changes are sent as one message
Receiving notifications
• Notification payload
• Does not contain the actual changes that occurred
• Contains the list of endpoints to invoke and the change type that
occurred
Receiving notifications

Sends the notification Notifies the client

payload whichever way
(push, pull, etc.)
 Click to add title
• _vjeko & _waldo

• Give us feedback in the App

• bros

• TODO: make at least 2 jokes

 Click to add title
• _vjeko & _waldo

• Give us feedback in the App

• bros

• TODO: make at least 2 jokes