With the April ’19 release of Business Central the standard API’s were released as version 1.0. According to the documentation, the beta version of the standard API’s remains available until April 2020 (Business Central 2020 release wave 1).
- API v1.0 pages are not part of the base application
- They are deployed as a hidden app, called _Exclude_APIV1_
- With navcontainerhelper you can download and extract the source code
The journey to find the source code
At Directions EMEA in Vienna, I watched a demo where the inventory of an item was changed by just setting the correct value of the inventory field via an API call. And I wanted to know more about it because I thought the inventory field is a non-editable FlowField. First I tested it by calling the API and search for the created entries. For a moment, I was afraid it would only create Item Ledger Entries, but I found out quickly that there were also Value Entries and G/L Entries created. Apparently, the correction was done through a normal Item Journal Line posting. So far so good. But I still had to answer the question of how it was implemented in code.
So I opened the v15 source code, searched for the Item Entity page (page 5470) and tried to find out what happens behind the scenes. Why did I look for the Item Entity page? Because that used to be the API page for items, like amongst a number of other Entity pages. However, it turned out that the page didn’t have code for creating Item Journal Lines. So, is it magic? No, of course not! Business Central can be a mystery, but it doesn’t create entries out of the blue. There must be something going on behind the scenes that I didn’t see.
Then I suddenly realized that I was looking at the beta version of the API page. The page was already part of the application before API v1.0 was released. And there is no version set in the API page, which means it is supposed to be beta (isn’t that strange by the way?). Anyway, I concluded there should be another page that serves the API v1.0.
But where? I searched everywhere in the source code of the v15 base application, but I couldn’t find any API page for the items v1.0 API. That’s not really satisfying, I can tell you. And when this happens nobody can stop me to find out what is happening. I will leave no stone unturned until I know exactly what’s going on.
I decided to create an event subscriber to the OnBeforePostItem event in the Item Jnl.-Post Line Codeunit. Set a breakpoint, debug the web service session (thanks to v15 that’s possible with attach next) and look at the call stack. And that brought me one step further to the answer.
The object APIV1 – Items was my suspect. It turned out to be page 20008 “APIV1 – Items”.
And it contains a function UpdateInventory that creates an Item Journal Line with the required change and posts it
But hey… where is this page hiding? Now that I knew the name and ID, I went back into the source code of the base application and tried to track down the page. However, it wasn’t there. For a moment I began to doubt myself. Then a suddenly realized there is another way to add features to Business Central: apps! 😀
PowerShell and navcontainerhelper helped me with the next step:
Now I could feel I was getting closer! The only thing left was to get my hands on the source code of this app, so I could verify the code and cross-check with the results from the debugger.
As you can see, the app name starts with _Exclude_. Such apps will not be visible in the Extensions Management page in Business Central. So I needed another way to get to the source code. Again, navcontainerhelper helped me with this final step (code can be copied):
Get-BcContainerApp ` -containerName bcsandbox ` -appName _Exclude_APIV1_ ` -publisher Microsoft ` -appVersion 15.0.36560.0 ` -appFile "C:\ProgramData\NavContainerHelper\apps\_Exclude_APIV1_.app" ` -credential (Get-Credential) Extract-AppFileToFolder ` -appFilename "C:\ProgramData\NavContainerHelper\apps\_Exclude_APIV1_.app" ` -appFolder "C:\ProgramData\NavContainerHelper\apps\_Exclude_APIV1_"
And there is the API page I was looking for!
After this journey, I felt somewhat unhappy. I found out what is going on behind the scenes, but did I really like what I found? Honestly, I think we shouldn’t have to find out these little secrets ourselves. Why is not clearly documented at the API documentation how the v1.0 API’s are deployed? And why hide away the app by excluding it from the extension management page? Why not publish the code, e.g. on the ALAppExtensions repo on GitHub? The source code of the base application contains the beta version, which will be deprecated in April 2020 and should not be used, while the actual code of the API is not available. Think about taking a standard API as a starting point for a custom API. You would probably take the API of the beta version instead of the latest version.
And then the point the journey started with. Setting the inventory by means of an API call that enables you to modify a non-editable field. That’s the scenario that triggered me in the first place. Now I know that the standard API page creates an Item Journal Line with a bare minimum of information, completely out of my control. I’m not sure whether I should like it or not. At least I’m not comfortable with it.
Anyway, I hope this journey helps you to take more control over the standard API’s of Business Central!
did you also write a blog post about api vs. 2.0? has microsoft added a better documentation? it’s really hard to find out. regards archer
What do you mean with API v2.0? As far as I know, there is no version 2.0 of the API’s.
Great stuff, but after reading it, I found a little more easier way 🙂
BC Install DVD and path: applications\apiv1\source
Yes, that is also possible. But not everybody uses the DVD to install.
As of today there are two other options:
– Get the app from the Docker artifacts
– Clone the ALAppExtensions repository on GitHub. The API apps are now part of it: https://github.com/microsoft/ALAppExtensions/tree/master/Apps/W1
Thank you for the pointer to GitHub–that seems to be the easiest way to get to the code.
In the GitHub folder: ALAppExtensions/Apps/W1/
There are two subfolders:
Is the V1 / V2 a reference to the BC v2.0 Environment / Tenant version? And the BC API itself is v1.0?
No, this has nothing to do with the /v2.0 endpoint that supports named environments.
API beta version is part of the base application, and the first set of APIs
API v1.0 was shipped as an app in v14 (April 2019)
API v2.0 was shipped as an app in v17 (October 2020)
API v2.0 has a lot of improvements and breaking changes, that’s why it was shipped as a new app. You control which version you use with the /api/
part in the URL.
As a result, the full URL has two versions in it:
Ah, thank you! So that IS a version 2.0 of the BC API? Somehow I missed that news! Thanks!