Convert REST endpoints from OpenAPI spec to GraphQL in 2 clicks

Modernizing REST endpoints to GraphQL is a very common process that we have seen from the community and enterprise users. This process can be simple or hard based on the complexity and how well the REST APIs are documented. OpenAPI is a way to document REST API endpoints in a machine readable format and is widely adopted in the software industry.

In Hasura terms, connecting a REST endpoint to GraphQL schema means creating a Hasura Actions, and one of the main challenge with the Action creation workflow is that it used to take some time when developers want to import multiple REST endpoints as they need to fill up the create action form for all the endpoints, but with the new import OpenAPI feature, creating an action from OpenAPI is 10x faster than before - with just 2 clicks.

Writing a GraphQL resolver yourself can be a cumbersome experience, developers are often reluctant to modernize their REST APIs with GraphQL, Hasura saves significant time in development and enables quick plug and play with REST API sources.

OpenAPI spec and GraphQL spec are fundamentally different, and hence getting a full feature parity may not be possible, with this feature we aim to make the developer experience of converting REST to GraphQL more easy as possible.

There are several reasons why you might consider moving from REST to GraphQL:

1. More efficient data retrieval: With REST, you often have to make multiple API calls to retrieve all the data you need. GraphQL allows you to retrieve all the required data in a single API call, which can be more efficient.
2. Better with brownfield projects: By adopting GraphQL as the gateway in a brownfield project already using REST APIs, developers can unify the data fetching process and get all the benefits of GraphQL without a complete re-architecture.
3. Better client control: In REST, the server determines what data is returned to the client. With GraphQL, the client has more control over the data it receives, and can request only the data it needs.
4. Easier to evolve APIs: With REST, evolving APIs can be difficult because changes can break existing clients. With GraphQL, you can add new fields to the schema without breaking existing clients, as clients only request the data they need.
5. Increased flexibility: GraphQL allows for more flexibility in the type of data you can retrieve, and can handle complex data relationships more easily than REST.
6. Better developer experience: GraphQL has a strong type system, which can help catch errors early in the development process. Additionally, GraphQL provides powerful developer tools, such as GraphiQL, which can help with testing and debugging.

In this blog we will see How to convert REST endpoints from a popular open API spec - Petstore OpenAPI into Hasura GraphQL Engine with access control in 2 clicks.

You can also read more about the feature in our documentation.

Step 1 : Preparing the OpenAPI specification JSON/YAML

OpenAPI specification is generally represented in JSON/YAML format, and Hasura accepts this directly as an input on the console.

Usually the OpenAPI spec will be maintained on a repository (like twilio) or some may have a link to JSON on swagger UI (like petstore), getting this spec file is all that you need to connect REST endpoints to Hasura GraphQL schema.

Step 2 : Load the spec on Hasura console UI

To load the JSON/ YAML OpenAPI spec on Hasura console, you can click on the Actions Tab -> Import from OpenAPI.

And paste the JSON/YAML file on the UI (you can also upload the file using file picker).

Once your specification is pasted/ uploaded you will now see the endpoints listed on the right hand side of the console.

In this example we will use the spec file from petstore openAPI .

Step 3 : Importing Endpoints to GraphQL Schema

Make sure you have a valid Base URL if this is not automatically populated. Some OpenAPI specifications may not have the server URL part of the specification, so when there is no base URL automatically populated, make sure you provide a valid base URL. In this example we have the base URL auto populated from the specification so we can move to the next step.

Once the above steps are completed, You can click on each Create button of each endpoint to import them to your GraphQL Schema.

By clicking on the Create button Hasura creates a Hasura Action under the hood and uses the OpenAPI spec to figure out the input argument types and available output data types.

You will now see the newly created endpoints listed as Hasura Actions on the left hand side so that you can add permissions or modify any configuration if needed.

Whoo! We have now connected a REST endpoint to GraphQL schema successfully 🎉.

Step 4 : Testing the endpoint

To test the new endpoint, you can head to the API tab and try out the new query. The GraphQL query type would be the same as in the OpenAPI specification.

You will also notice the input payload arguments and URL template arguments are now part of the GraphQL input type so that you can make GraphQL queries as dynamic as the REST endpoint.