In Dynamic 365 for Finance and Operations the service endpoints we create are deployed automatically upon build, without the need of any additional setup or configuration we used to do with legacy AIF services. However, in current API services, we do not have many of the configuration possibilities which were provided by WCF configuration and inbound/outbound port management before. Azure API management service is an Azure service that provides a highly configurable front end for every sort of Azure and 3rd API services, also for our D365FO API service endpoints.
Adding D365FO API services to Azure API management brings up many advantages. Some of those are :
Unfortunately, in the time of writing, it is not a straightforward process, like clicking a button on D365FO UI and adding your service directly to API management. So we need to struggle a bit to be able to achieve this.
To begin with, we need a D365FO API service for testing in API management service. In this example I will use the same service I have created for my previous blog post, the visit schedule service in How to connect a Native Android Application to Dynamics 365 FO. You can download and install the D365FO project file for this service from the link below : https://github.com/sertanyaman/native-android-integration-example-for-dynamics-365fo
Then, create an API management instance from Azure portal. The name you give to your management instance will be the used as the url prefix to access all your API services like “https://<managemeninstancename>.azure-api.net/<apisuffix>“. After the service is created (will take a long time) open it in Azure portal, go to products tab and create a new Product. This step is optional for testing, but it is a good practice to use a product for all D365FO services to organize them together from the beginning:
The API manager will create a default subscription for that product in the subscriptions tab with all the needed keys.
Then we need to register an application ID for our API management frontend to access D365FO using Azure AAD, as described in the link below : https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app
choose “Accounts in any organizational directory” option in the creation of your app registration and note your application (client) ID GUID after the creation. We will use that later. Go to API permissions tab from here and add the following permission to your app registration:
Go to Certificates & Secrets tab and add a new client secret. Note this value to be used later :
Go to overview tab and open endpoints window, to copy some values from here later.
Leave this window open, we are not finished with it yet, and open another azure portal window with your API Management setup. Go to the Security>Oauth 2.0 tab here and add a new OAuth2 service. Fill the values as shown below :
Save your settings and go to the APIs tab to add our D365FO service endpoint. Here you have many options for adding an API to your API management. You can add logic apps, azure functions as well as WSDL and Open API documents. Unfortunately there is in the time of writing no option for us to generate an OpenAPI specification document for our D365FO service endpoints. So we can either write the OpenAPI document manually ourselves or use the Blank API option here. Click on the Blank API button and add specifications for your service endpoint. For the visit schedule test service, add the following URL suffix to your base D365FO url : “/api/services/AndroidTests/AndVisitSchedule”
The “API URL suffix” field here is for the Azure API management service URL itself, and you are allowed change this anytime you like. Do not forget to add this API to the D365 product we have created before, and save your changes. After save is complete, open the settings tab for your API and from here configure OAuth 2.0 authorization as shown below :
Here in the setting page we can also disable the requirement for subscription keys. For this test, we will not going to do that and show how you can add extra security using subscription keys.
Now lets add our service operation. The visit schedule demo service has two service operations. Here we add the “getNewTasks” operation to the API management service :
It is also nice to give a tag for d365 service operations because we can use this tag for filtering metrics and logs later. Leave the rest empty and save the operation.
Is that all of it? Is our service ready for testing now? No, not yet!…
Now go back to the App registration page in your Azure AAD and in the Authentication tab add the following value with type “Web” in your Redirect URIs : “https://<yourapimanagementname>.portal.azure-api.net/docs/services/<youroauth20serviceregistrationname>/console/oauth2/authorizationcode/callback”
The API management name is simply the same name prefix which is used in your API management URLs. The oauth service registration name is the name of the setting you used in the previous step for creating oauth2 registration for the API management. If you do not include this setting, you get an error on the AAD authorization used by the Developer Portal Test page of API management.
Now in the end, we are ready to test.
First create some demo records in visit scheduling to be picked up by the service. Open the visit scheduler form and enter some records:
Now go back to the API management page in Azure portal, and open “Developer portal” from the buttons in the toolbar. Here click APIs and the click on the API you have just created. Here you can run your operation and copy the code blocks needed to call the service in different programming languages. Click on your operation and click “Try it” to open the test page.
Here you need to define the authorization and the Request body. The rest you can leave as default since we did not create more than the default subscription. Click on the Authorization combo and select “Authorization code”. follow the steps in the popup windows if you need to authorize in AAD. The token received from AAD after that operation will be automatically added to request headers.
On the request body, we need to fill the parameters to call our service in JSON format. We have only one parameter, which is “_worker”, so add a JSON value for the worker id (the worker id we created demo data for) as shown above. Leave the rest of the values in the screen and hit “Send” and Voila!. If everything is correctly set, you will see the results coming from the service as shown below :
See that we can also trace the service request and see the steps involved in calling the service from the Trace tab here.
And what about testing the API management Frontend service directly using 3rd party applications? To achieve this, you need the subscription keys created for your product in Api management (product D365). Go to the subscriptions tab and copy the key value from the primary key of your product’s default subscription (Or copy it from the test window trace we used above). Then use your favorite REST client, here I will use PostMan, and setup a call to your API management operation frontend URL, like shown below.
Open the Headers tab of the request and add a header with a key of “Ocp-Apim-Subscription-Key”. For header value, paste the subscription key you have copied. Now we also need to setup an AAD authorization to be able to acquire a token and call our service. PostMan easily arranges that for you. Go to the authorization tab and select OAuth 2.0. Click “GetNewAccessToken” and from the popup select Grant Type of “Authorization Code”. Fill in everything just the same as you have done in the API management OAuth2 setting, for the CallBack URL, just select one of the redirect URLs you setup for your AAD app registration. Click Request button and follow the steps for AAD authorization. Once finished, a token will be shown to you, click “Use token” on the bottom and you are done.
Now before testing the visit schedule service again from PostMan, you may want to create new demo data or reset the visit schedule staging by clicking “Re-initialize” in the D365FO visit schedule form. Otherwise you will get empty results.
After that is done, go back to the postman window and click “Send”. You will see the results coming (again if everything is setup correctly) :
And if you go back to your API management dashboard, you can directly see the metrics and request counts for the service operation you are testing now. Cool isn’t it? :