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.

1. Adding Action Permissions : Once a REST endpoint is added to Hasura, you will be able to add access permissions to these endpoints. This helps you to make this REST endpoint accessible to only a set of users who access the GraphQL API.
2. Additional configurations : Imported actions from OpenAPI spec can be modified like any other Hasura Actions - This means you could,
3. Hide sensitive information like Access Keys by setting it as env variables.
4. Customize REST Connector transformations: Provide default values, merge or transform graphql input values to REST API payload/query parameters/ URL itself

• Supported HTTP Request Types
  • GET
  • POST
  • PUT
  • DELETE

• Query Parameters : While converting a REST endpoint to GraphQL, Hasura will parameterise the query parameters into GraphQL input types.
• Header Parameters : Hasura can even take inputs from GraphQL input type and convert that into HTTP request headers and make HTTP requests.
• Request URL Template/ Path Parameters : When there is a templated HTTP URL or path parameter specified in the OpenAPI specification, Hasura will convert them to GraphQL input types to make that available on the GraphQL query.
• Request Body Type : JSON/ form-url-encoded are supported to be used while adding a REST API to GraphQL schema.

Note: The Import OpenAPI is a feature that helps you to configure Hasura Actions from OpenAPI spec, if there are any incompatibilities you could configure an Actions manually from Hasura Console.

Summary

If you have a large OpenAPI spec that you want to modernize and power up with GraphQL. Hasura makes it easier and faster by providing plug and play configuring experience, this can save significant time in development  and helps you to focus on what you build, instead of worrying about writing - long resolvers, access control handlers, data transformers, etc.

You can try this feature on all Hasura offerings - Cloud, Enterprise and open source community edition.

Try creating a Hasura project and connect your first REST endpoint to get a GraphQL endpoint all in under 5 minutes. Sign up to get started!