OpenAPI is key to build rest-clients with maximal comfort 💪 .
Looking at powerful connectors in the Market, you are surely convinced of that.
But how can you join the API game? Where is the OpenAPI for your specific service to be found?
Despite the broad support for OpenAPI by many vendors, there is yet no standard way to resolve its specification. Here's how I proceed to get it:
Browse the dev-docs
For most third-party systems you simply need to look for an openapi.json
or openapi.yaml
file, which is published in their docs. By example Github, has a prominent landing page in their docs, for OpenAPI descriptors.
OData
Many vendors that build upon a Microsoft backend use the OData spec as meta-protocol to describe their services. If your third-party depends on OData, just fire a $metadata request to get the service-specification in OData format and safe the output to a file. Afterwards you can convert this file to OpenAPI. As we have this case quite often, for SAP and other platforms, we published a simple public odata-converter-service, where you can run this conversion.
Postman
Postman is a popular tool to develop REST API requests. With its collection capabilities, it has become a first-class tool to share valid requests with and audience. These collections can be transformed in to OpenAPI by using the npm-postman-converter. We have successfully used this to turn the postman collection of our sister DocuWare into an OpenAPI DocuWare connector.
Community
The OpenAPI initiative formed a huge group of world-wide admirers. Therefore many developers started to describe services, which are not under their control, with an OpenAPI spec. As the format is simple to write, this can be done without the consent of the service provider. So, if you can't find an official openapi.json/yaml, try to find one in the web by looking up the search term "<your-service> openapi". We work with a third-party descriptor too, to build our Amazon connectors. Thanks to the devs from api.gurus, we didn't need to write the OpenAPI spec on our own.
Manually
If no OpenAPI can be found after thorough research. You should be the one starting to publish one. As it provides a lot of value, when you craft a connector for a bigger audience. Validation, Docs, strongly typed objects ... everything comes for free if you just have an OpenAPI. Note, that you don't have to describe every detail of this foreign service, but just the use-cases you want to reflect in your connector. The swagger-editor ✍️ is a good tool that comes with sample openapi descriptors and validation features for your docs.
We have authored openapi.json descriptors for third-parties successfully in the past. By example to craft our currency-converter.
Use the OpenAPI 🚀
Once you have an opeapi.json/yaml file. You are ready to generate an ivy rest-client for it and fire your first requests.
Read about this in our Rest-Client docs.