and funny enough, it was my own colleague Márton Sági who pointed me in an interesting direction. Let’s see if we can convert that edmx in something more useful: an OpenAPI description of our (custom) APIs! I reached out to the twitterz. Well, I can tell you – that’s not an OpenAPI – and in general, the developers at the customer are going to be a bit disappointed in that kind of documentation. Or even better: “ $metadata?$schemaversion=2.0” to also get the enum-descriptions.įrom the docs: Use OData to Return and Obtain a Service Metadata Document – Business Central You can simply get to the edmx by adding “ $metadata” to the url.
Which basically is an XML description of your APIs. Well, the most basic description we can give to our customer/3rd party is what we call an “edmx” (Entity Data model XML).
you know, they don’t exist “out-of-the-box” -). And this definitely doesn’t exist for custom API’s out-of-the-box, as. this does not exist out-of-the-box for Business Central.
#Swagger ui text blocks update
Even more, this screenshot also shows the abilities: like, I can only read the accounts, but I can read, update and delete trialbalances (if that makes any sense.
#Swagger ui text blocks how to
And a screenshot of what it could look like, if you would have some kind of graphical UI that makes this JSON or YAML much more readable:Īs you can see – a very descriptive page, with a list of API endpoints, a description on how to use them, and even a way to try them out, including details on what the responses and requests would have to be. I’ll simply give you a decent resource for you to read up: OpenAPI Initiative () / OpenAPI Specification (Swagger). There is a lot to say about this, and I don’t want to bore you with the specifics. An industry-accepted-standard sort to speak.
It is basically a JSON or YAML file, that can be represented in some kind of UI to make it very readable, testable. As such: a document (or set of documents) that defines/describes an API following the OpenAPI Specification. What would I expect as a decent, useful description of an API that I’d have to use? OpenAPI / SwaggerĪnd we can’t deny that when we need to integrate with something, we LOVE to get some kind of OpenAPI / Swagger description. When you get questions like this, it makes sense to try to find out what they like to get as an answer. Let’s see if we can find a decent answer. The reason for this blogpost is merely because recently I got the question “ how do I communicate this API that I just made with the customer that has to use it?“. I’m just an enthusiast, that tries to find his way in the matter. I’m by far not an API god, guru, master or whatever you call an expert these days -). Now, before I continue, let’s make one thing absolutely clear. When done, you have to communicate this to the 3rd party for them to implement the integration, so you need to pass the documentation, and kind of help through “how to use Business Central APIs”, and a description of the responses, requests and possibilities you have with “typical” Business Central APIs. You’re at a project, you had to implement an integration with a 3rd party application, and you develop some custom APIs for it. For reasons that are not too important, I am trying to find a way to “describe my custom APIs”.
0 kommentar(er)
