In this blog post, we'll take a deeper dive into what GraphQL is, how it works, compare it to REST, and most importantly, how and why we use it at RootFi.
GraphQL is a query language that allows developers to efficiently retrieve the data they need from their APIs. In other words, GraphQL is a way or style of calling data. Developed by Facebook in 2012, GraphQL has quickly gained popularity and is now used by major companies such as GitHub, Shopify, and Yelp.
At its core, GraphQL is based on three main concepts: types, queries, and resolvers.
Types describe the shape of the data that can be retrieved and manipulated through GraphQL. Types can be scalar types (e.g. String, Int, Boolean) or complex types (e.g. Object, Array). Types can also be extended using interfaces and unions, which allow for more flexibility and reuse.
Queries are used to retrieve data from the GraphQL server. A query is a JSON-like object that specifies the data that is requested and any arguments that are required. Queries can be composed of multiple fields, which can be scalar types or complex types.
Resolvers are used to determine how data is retrieved from the server. Resolvers are functions that map fields in a GraphQL query to the data that is retrieved from a data source (e.g. a database). Resolvers can also perform data transformations and validations, making them a powerful tool for building complex APIs.
REST, SOAP, and RPC are the common alternative API styles. SOAP and RPC were popular in the ’90s and 2000’s with REST taking over in being the dominant API, communication protocol. However, interest in and a community GraphQL has been steadily growing over the past decade. Postman is now a GraphQL client too.
The debate between using GraphQL vs. REST API is popular amongst developers. Unlike traditional REST APIs, where you send a request to a specific endpoint and receive the data available at that endpoint, GraphQL APIs allow you to specify exactly what data you need and receive only that data. This is done through GraphQL queries, which are sent to a single endpoint that serves as the entry point for all queries.
One of the key benefits of GraphQL is that it allows you to retrieve all the data you need in a single request. This is because a single GraphQL query can specify multiple fields and nested objects, and the GraphQL server will only return the data that you requested.
Using fewer queries reduces the number of round trips required between you and the server, resulting in faster and more efficient data retrieval. This is especially beneficial in a category like accounting, where reads require multiple fields and pull from nested objects.
Another benefit of GraphQL is that it provides a strongly typed schema that describes the available data and operations. This means that you know exactly what data you can request and what operations you can perform on that data. This is particularly useful when working with large and complex APIs, as it allows developers to understand the API more easily and reduces the likelihood of errors.
Performance issues can be a concern since each nested object in a GraphQL query requires a database call, and a complex nested query can overload a server. In this way, GraphQL’s biggest advantage also becomes its greatest weakness.
The industry solution is to calculate the query cost before running the query. Essentially, this means counting the number of nested objects that are present before running the query.
Furthermore, RootFi’s solution is to restrict the number of objects we return per page. We believe this tradeoff does not negatively impact you as there are very few use cases where one needs to retrieve a vast number of records per API call.
GraphQL is certainly more complex to implement and maintain than REST due to the need to implement types, queries, and resolvers. For simple APIs that primarily focus on CRUD (create, read, update and delete) queries REST is the recommended route.
At RootFi, we believe this additional complexity is important due to the nature of our complex, nested relational data models and that using GraphQL to read this data will greatly benefit you.
Error handling is easier in REST since it follows the HTTP specification emitting various HTTP statutes for different API states. On the other hand, GraphQL does not have any standard responses and returns an error 200 response.
To solve this problem for you, we have mapped the most common GraphQL errors to our Unified Error Handling feature. We try and return REST-like responses for common errors like authentication and query validation. In many cases, we also pass along with the underlying GraphQL messages to help you debug the error messages through your platform.
"We use GraphQL for our read APIs because we have complex nested relational objects. GraphQL's self-documenting API enables our customers to easily fetch the exact data they want.” - Parth Shah, CTO & Co-Founder
In essence, GraphQL is designed to allow you to customise the fields you want to retrieve, which is especially important with many nested fields. Additionally, since the request and response format is the same, GraphQL becomes a self-documenting API, which gives you ease of use in addition to flexibility. RootFi uses GraphQL for read APIs as it allows you to abstract away complexity and quickly retrieve the exact data you want. Here’s an image from our GraphQL playground.
Finally, we have REST APIs over our GraphQL APIs, so if you do not want to use GraphQL or start testing quickly, you can use our simple REST endpoints. However, we still recommend using a combination of GraphQL for read APIs and REST for write APIs.
In conclusion, GraphQL is a powerful and efficient query language that allows developers to build flexible and extensible APIs. By allowing you to specify exactly what data you need, GraphQL reduces the amount of data that is transferred between you and the server, resulting in faster and more efficient data retrieval. Additionally, the strongly typed schema provided by GraphQL makes it easier to understand and work with large and complex APIs, reducing the likelihood of errors and making development more efficient.
Get started with this new technology today. We recommend Apollo GraphQL, which is leading the way with GraphQL adoption. You can learn via Apollo GraphQL Tutorials and also come onto our playground. Sign up to experience our GraphQL playground or book a demo to talk to us about getting started with RootFi’s Unified APIs. Alternatively, check out our documentation!