REST APIs to GraphQL — Switch with Stitch
Introducing Stitch, a lightweight GraphQL schema generation tool
A brief history of REST APIs
If you’ve ever used an application that communicates with the internet, chances are you’ve interacted with a REST API. But what exactly is a REST API?
REST, or Representational State Transfer, is a software architectural style that was introduced in 2000. REST provides a standard way of accessing resources over the internet using HTTP protocol. In other words, it’s a set of guidelines for how to design web services that can be easily accessed and manipulated.
There has been some criticism of REST in recent years. Some developers argue that it’s not always the best choice for building complex web services, and that alternative architectures, like GraphQL, may be better suited for certain use cases. That is because traditional REST API architecture is prone to over and under fetching data, and can be difficult to scale.
What is GraphQL?
GraphQL is a query language and server-side runtime for APIs, and has emerged as an alternative to the traditional REST API architecture. It allows developers to request only the data they need, and grants clients increased flexibility in how they structure their queries.
Utilizing GraphQL to handle API requests prevents both over and under fetching data. In typical REST API architecture, clients request data by hitting endpoints that return pre-configured data structures, and it is difficult to design the API in a way that is tailored to the client’s exact needs.
Over fetching occurs when the endpoint provides more data than is actually required in the application. Under fetching occurs when a specific endpoint does not provide enough information, and the client must make additional requests to different endpoints to fulfill all data requirements of the application.
GraphQL uses a strong type system to define the capabilities of an API, and these types are configured in a schema. The schema serves as the contract between the client and the server to define how a client can access the data. Once the schema is defined, frontend and backend developers are able to work independently as the data that is sent over the network is definitively structured. GraphQL provides many optimizations over traditional REST API architecture, and implementing it in an application can provide many efficiencies when querying for data.
Migrating from REST to GraphQL
Once the decision has been made to migrate from traditional REST API architecture to GraphQL, the migration process will require the client to do a deep dive into the existing file structure and develop a comprehensive understanding of the current endpoints and response data. This can be extremely tedious, and the process can be complex and error prone. The client will need to configure GraphQL schemas according to the existing endpoint structure, and this process can pose a lot of issues and complications.
What is Stitch?
Stitch is a lightweight GraphQL schema generation tool. Stitch allows users to visualize their existing REST HTTP endpoints, and easily generate and reconfigure the respective response objects into GraphQL schemas. Stitch provides users with the ability to add multiple HTTP endpoints to the application, easily view the response objects associated with each endpoint, and customize the response objects into GraphQL compliant schemas, ultimately allowing for a more seamless GraphQL migration process.
How do I use Stitch?
Stitch can be used directly from your browser. Just navigate here and you’re off!
Adding endpoints
- Copy/paste any endpoint that provides a JSON response into the input field and click Add. Your endpoint will populate in the Endpoints view, and the data associated with the endpoint will appear within the JSON Response view.
- You can add multiple endpoints to the application, and clicking on the endpoints in the Endpoints view will allow you to quickly navigate between the different JSON responses.
Adding schema fields
- Once you’ve added endpoints, you can click the ‘+’ button associated with each line of the JSON responses to add the desired fields to the GraphQL Schema view
Configuring your GraphQL schema
- As you add types to your schema, those will appear immediately in the GraphQL Schema view. The data types are initially inferred, but can be edited through the drop down menu associated with each schema line item. You can also set types to be required, or delete types that you no longer want to include in your final schema.
- The Type input field allows you to name your schema. Simply type what you wish to name the schema and hit ‘Submit’. You’ll see it reflected instantly in the schema view.
Exporting your GraphQL schema
- Once you have your schema built to your liking, you can click the copy button to copy to clipboard and paste it into your schema.js file in your app.
Authenticating through Github
- You can connect your Github account to unlock saving and loading views.
- Once authenticated, you will see extra fields that allow you to save any created schemas, as well as load any previously created and saved schema views.
Saving Views
- Add a name to your current view and click Save. Your saved view will appear in the drop down menu next to the ‘Save’ button.
Loading Views
- To select a previously saved view, simply click on the drop down menu and select the desired schema view.
Conclusion
Try Stitch out for yourself! Stitch is an open-source product that is open to input and feedback. Check out our github repo and open a pull request!
Stitch, developed in partnership with OS Labs — Beta