From OpenAPI to a working integration in minutes

tl;dr: Use Integration designer to create an API integration from OpenAPI document immediately usable in your application with OneSDK. Publish the integration to the public registry and download a generated starter project.

You are supposed to integrate a new service via API. Hopefully, that API has some documentation. Even better, that API has a specification, like OpenAPI Description. What is your next step? Will you painfully write the integration code manually? Or let the computer automate the boring parts for you?

Dealing with API integrations isn’t fun, which is why we are building Superface in the first place. While you can install a ready-made integration from the catalog, writing a custom integration used to be a manual process.

Now there is another option: generate the integration using the Integration designer. This tool takes an OpenAPI Description document for your API and creates an integration for a single API endpoint. You can immediately try the generated integration from your browser, publish it to the public registry, and download a starter project.

How it works

The designer normalizes the OpenAPI Description with Stoplight’s HTTP Spec library. This library also handles Swagger documents and Postman collections, which we may support in the future.

Once you pick an endpoint, the designer splits the integration into three parts:

• Profile, an interface definition which describes the structure of input and output data,
• Map, which describes the integration logic – which endpoints to use, how to format the data and how to pass the output,
• Provider definition, specifying a base server URL and security schemas used by the API.

Once generated and properly named, the integration is ready for consuming by OneSDK. The in-browser demo executes the integration with a serverless function using a simplified version of OneSDK.

What makes it different

There are a handful of tools for generating SDK from OpenAPI Description, so what makes the Superface integration designer better?

• Maintenance: Superface integrations strictly decouple the interface definition (profile) from the integration logic (map). With this approach, you can maintain the logic independently and, if needed, swap the providers without affecting your application’s code.
• Reusability: If you decide to publish the integration into the public registry, you can install it into multiple projects without dealing with packaging.
• Evolution: Additionally, you can update the published map in the registry. Applications using OneSDK can fetch the updated map in the runtime without need for redeploy.

Other benefits of Superface apply as well. Since OneSDK performs the integration logic locally, as part of your application, you are not limited by the number of executions. You can use Superface integrations with private APIs inside the company's VPN. And there is no middleman or proxy server between your application and the API: your data never touches Superface servers.

Try it yourself

Try the integration designer with your OpenAPI documents. If you don’t have any document handy, we prepared a few examples for you, or you can find more OpenAPI documents on APIs.guru.