How to use OpenAPI to accelerate low-code/no-code API development

Table of Contents

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. 

creating API to manage support case

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

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

Create new API collection in Workato

Select Import OpenAPI Specification and upload the file.

Import OpenAPI Specification

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

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

Select recipe location

The result is a complete API collection, including a recipe for each endpoint.

Complete API collection

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

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:

All without additional development or ops overhead.

Also read: Custom API Security: How to use custom API calls securely

Was this post useful?

Get the best of Workato straight to your inbox.

Table of Contents