Moving to GraphQL from SOAP or REST

This blog is the fourth part of the series called “API Transformer Recipes”. The series aims to highlight numerous ways in which developers can integrate API Transformer into their workflow in order to gain access to a wide range of tools and frameworks. Hopefully, it will help eliminate any assumptions that they have about being restricted to a particular set of tools just because they use a certain API specification format. Links to previous blogs in this series: Facilitating Migration from SOAP to REST, Enabling Postman’s Team Sharing Features for OpenAPI Users, Opening ways into IBM API Connect

Announcing support for GraphQL Schema

Oh yes, you heard it right. You can now export GraphQL Schema from APIMatic using API Transformer! Previously, we provided our users means of migrating from SOAP to REST, and now also aim to facilitate those SOAP/REST users looking to migrate to GraphQL.

Why GraphQL, you wonder? Without going into details, GraphQL is known for being simpler, faster and efficient allowing users to fetch exactly the data they need. Many strongly believe that GraphQL is the future of APIs. So if you are one of them and are considering moving to GraphQL, read on.

Our support for GraphQL schema is currently in beta so we are open to any feedback/suggestions that you might have.

Role of GraphQL Schema

GraphQL schemas for a service are defined using GraphQL SDL (schema definition language) having a pretty simple syntax for defining various components like types, queries, mutations etc. We’ll take a look at some examples later in this blog.

A GraphQL schema is at the core of any GraphQL server implementation. It describes the functionality available to the client applications that connect to it. So having this schema file will serve as a key starting point for migrating your API to GraphQL. You can then easily generate server code, resolver signatures, etc. from it using various tools available out there.

Export GraphQL Schema Files with API Transformer

Bring your API files and export them to GraphQL schema using API Transformer. All major input formats (e.g. OpenAPI, RAML, API Blueprint, etc.) are supported.

The following features of the schema are supported:

• Object types
• Scalar and Enumeration types
• Input types
• Arguments
• Queries
• Mutations
• Lists and Non-null fields

GraphQL itself does not impose any strict naming conventions other than a list of allowed characters mentioned in their spec. However, keeping in mind some of the best practices highlighted for GraphQL schema design, mutations and GraphQL enum types, we follow some conventions to make the migration process for our users easier. These conventions aim to facilitate development and interoperability.

Conventions

• The names of various components will obey the rules specified in the spec.
• Object/Input and Enumeration type names will be pascal cased.
• All field names will be camel cased.
• Enumeration field names will be upper cased to represent their nature as constants.
• HTTP verb will be prepended with query/mutation names to represent the action that will be performed upon calling it.

For SOAP Users — Migrating to GraphQL

With API Transformer, SOAP users can start migrating to GraphQL by obtaining a GraphQL schema file from their service WSDL file. This involves a conversion of all WSDL types to GraphQL schema types, operations to mutations and attributes to arguments. The example below illustrates this:

WSDL example:

GraphQL schema obtained by converting above WSDL file using API Transformer:

For REST Users — Layering GraphQL on top

Instead of completely migrating to GraphQL, users generally prefer to add a GraphQL layer on top of REST and enjoy benefits of both. The choice is yours depending on your service and system needs.

You can convert your RESTful API defined in one of the popular formats like OpenAPI/Swagger, RAML, etc. to GraphQL schema with API Transformer. The conversion process will:

• Convert GET operations to GraphQL queries while other operations involving server-side changes to GraphQL mutations.
• Convert complex types in the API to GraphQL object and enumeration types.
• Wrap operation parameters in a GraphQL input type and link that input type to respective query/mutation arguments.

The example below shows the conversion:

OpenAPI 3.0 example:

GraphQL schema obtained by converting above OpenAPI 3.0 file using API Transformer:

Conclusion

We hope you found our migration guide to GraphQL useful. If you have any feedback for our GraphQL schema export feature, feel free to reach out. If you liked the blog, show your support through your claps 😁

Continue reading more API Transformer Recipes:

• Enabling Postman’s Team Sharing Features for OpenAPI Users
• Facilitating Migration from SOAP to REST
• Opening ways into IBM API Connect
• The Whys and Hows of Exposing a SOAP Service Using Your REST API