What is OpenAPI?
OpenAPI is a universal standard for designing and describing APIs. When developing APIs it’s vital to consider the experience of the consumer. Consuming an API is a user experience, just as much as using a visual UI.
Therefore, to create a positive user experience, you need to invest in API design. And just like UI designers create wireframes and mocks in tools like Figma and Sketch, API developers have their own design tools, like Postman, Swagger, Apiary, and Stoplight.
Developers use API design tools to sketch out the details of a suite of APIs in an industry-standard format called OpenAPI.
What is inside an OpenAPI specification?
An OpenAPI specification sets out:
- The title and metadata for the API
- Each supported path (like `GET /cases/{case_number}`)
- Required parameters for each request
- All possible responses to a request, including errors
- Details of the business objects handled by the API (such as cases, invoices, etc)
The OpenAPI spec can then be used to automatically generate documentation or even a mock server that consumers can use to develop API clients before the API is production-ready.
Benefits of using OpenAPI — rapid development
A key benefit of designing in the OpenAPI format is that it lays a foundation for rapid development. Code developers have long used code generation tools to take an OpenAPI spec and generate a “stub” of an API server in their preferred language and framework.
This stub will include all the paths, responses, and data objects required by the API, leaving the developer to focus only on coding the business logic.
Related: A faster way to build performant APIs with low-code/no-code
How to generate an API Collection from an OpenAPI specification in Workato
Now, low-code/no-code developers working in Workato can also take advantage of OpenAPI specs to speed up the development of APIs. Simply import an existing OpenAPI spec into Workato, and we’ll automatically generate an API collection, and create an API recipe for each endpoint.
Each generated recipe will already include:
- Input fields
- Each possible response, including errors
- Output object for each response
All you have to do to release a working API is complete the business logic in each recipe.
How it works
To show you how to turn an OpenAPI specification into an API Collection, we’ll work through a very simple example of a SaaS company creating an API to manage support cases.
Case study: SaaS company creating an API to manage support case
The API provides limited access to backend systems that can be safely used by three different consumers:
- Customer service teams using the internal support app
- Individual customers using an online support portal
- Retail partners using their own internal systems
Step 1: Draft your OpenAPI document
During the design stage, the team works with all three groups of stakeholders to determine what actions they need, and what details of a support case are necessary. The result of this collaboration is an OpenAPI document drafted in Postman.
OpenAPI document drafted in Postman
Note that this document defines:
- The requests that can be made to the API
- Possible responses to each request
- Detailed definition of the customer support case object
Step 2: Generate an API collection from an OpenAPI specification in Workato
In your Workato account, navigate to API platform > API collections and click Create new API collection.
Create new API collection in Workato
Select Import OpenAPI Specification and upload the file.
Select ‘Import OpenAPI Specification’ to create your new API collection
Workato will extract all the API endpoints from the file. If necessary you can edit names and details of each endpoint.
Workato extracts API endpoints from your OpenAPI specs file
You’ll also get a collection name, version, and description as long as they’re present in the file. Just select a location to create the recipes for the collection.
Select recipe location
The result is a complete API collection, including a recipe for each endpoint.
Complete API collection
Drill down into the recipes and you’ll see that the request and response schemas have already been created for you.
Request and response schema created
Step 3: Create the business logic
Now all you need to do is add actions to each recipe to create your business logic.
What’s next?
With the help of the OpenAPI specification, you’ve created a complete working API. Through the API platform you can now:
- Create access and security profiles to enable your consumers
- Deploy to a custom URL
- Stream all logs to your preferred platform
- Scale automatically with demand
- Manage future changes and versioning
All without additional development or ops overhead.
Also read: Custom API Security: How to use custom API calls securely