GraphQL vs REST - a low-code API showdown
REST and (the newer) GraphQL APIs are the core technologies behind the vast most of today's integrations. These APIs allow external developers to tap into the functionality of the major platforms and build in their custom functionality to suit their needs.
The fundamental difference is that REST is an architectural design framework based on HTTP, while GraphQL is a query syntax that is not transport-dependent.
The introduction of GraphQL allows developers to send and receive data much more efficiently, focusing on performance and optimisation. GraphQL queries are based on the relationships between data objects, enabling you to query multiple related resources in a single call. On the other hand, interacting with REST APIs requires applications to make several requests to multiple endpoints and then use the returned data in subsequent requests to get the final needed data.
When looking at these two technologies in the context of low-code development, and depending on your specific needs, you might prefer GraphQL over REST and vice versa.
Let's compare the two technologies, considering the high-level areas of development:
Let's get started;
GraphQL wins this debate on performance and optimisation. Particularly in terms of bandwidth usage - as long as you structure your queries properly, you can only retrieve the data you need in a single call instead of making several requests that limit the bandwidth used on both my side and the server.
The ultimate strongpoint of GraphQL is performance, and depending on the amount of data you are integrating with, this is a significant advantage.
With REST requests, the major drawback in achieving complex data manipulation or retrieval is that this typically requires multiple requests executed in subsequent order to get the necessary amount of data. This process presents a challenge in meeting API request limits, bandwidth usage, and overall system optimisation. However, depending on how much data you are processing, this might not be an issue. Your design strategy may include storing a local copy of all the relevant data from your target system, which you can then use to execute further logic and work out the relationships without affecting the bandwidth usage.
REST endpoints suffer from two issues in terms of data retrieval, namely
Endpoints return only a subset of the information that you require. Unfortunately, this leads to the scenario where you need to execute several requests subsequently to retrieve the complete set of data. Depending on the API and your specific needs, this can enormously impact optimisation and scalability, so it always needs to be kept in mind.
In this scenario, too much data is returned in request responses, even though you may only require one or two attributes. With some systems, you can indicate which fields you need from the API server, but this is not standard behaviour across the industry. This leads to unneeded data being returned in your requests, which presents challenges by incorrectly parsing the returned objects and using unnecessary bandwidth.
Learning a new syntax can be challenging and often avoided in today's low code environment. However, much like database scripting languages such as SQL, learning a new syntax language can be very powerful and enable you to perform much more complex functionality. Therefore, you need to weigh the benefits of more complex functionality with a steeper learning curve in terms of rapid development.
GraphQL is a query language, and thus it requires a whole new range of knowledge on how to script out instructions to achieve your goal. Moreover, GraphQL requires you to type out complex JSON structured queries in a particular syntax, which presents a significant drawback in rapid development and low-code in the current environment.
You first need to understand the specifics of the syntax before you can even start proving your concept or working with the data you need. In addition, slight errors in your syntax may become frustrating as it is challenging to determine where exactly you have gone wrong. There do exist 'GraphQL Explorers' such as GraphiQL, which makes the task of testing out your queries somewhat easier. However, due to GraphQL being fairly 'new' on the scene, testing tools that score high on usability and ease are rare to find. However, the payoff ultimately comes when you've conquered this learning curve, and you are finally able to implement robust, perfectly optimised functionality.
In the context of rapid development, this presents a hurdle as you will need to investigate the various data objects to determine which fields you need or require in the response and the particular name of each field. Often, you want to 'play' around with the possible data and see what exists on the system for each object which is not that straightforward from GraphQL documentation. However, once you're familiar with a specific platform's data structure, you can start working with the data and begin implementing your custom logic.
When working with REST APIs, data is loaded from specific endpoints, each dealing with a particular task or method of a single type of data object. Each REST endpoint has a clearly defined structure of the information that it returns, and this data is typically only related to a single data object. This advantage is that you can quickly integrate with a particular system based on your higher-level data requirements. Even though calls return data that sometimes might be overkill, you can at least view the data structures immediately without having to delve into the particular fields of each response and determine what specific data you need in the long run.
Reusability and modularisation should be critical concerns when building any system or integration. This is particularly important as future developers would need to understand the codebase to maintain the system.
GraphQL queries are written in a syntax that is not entirely obvious to understand. Therefore, when creating large and complex queries, you may want to re-use them slightly differently, which means either re-writing the whole query out again or copying the query text and tweaking it in the various locations within the query itself. Unfortunately, this process slows down development and also introduces a greater scope for error.
REST requests all follow a similar structure, and by modularising each request to achieve a single task, you can interchangeably use these requests without altering them. Furthermore, making a similar request is relatively easy to copy and change one or two properties without delving into any syntax code.
The flexibility of integration will depend on the task at hand. However, like with all custom development and integration, your needs will be specific to you, and thus the more flexible a system is to your needs, the better.
GraphQL is a query syntax where the request is made to a single URL/endpoint. Therefore, developing custom functionality on a front-end system is far quicker as you can query the exact data you need and not rely on developing specific endpoints. Additionally, due to GraphQL being a query syntax, you do not have to rely on specific methods being created for every bit of data you want; instead, you need to script out the proper combination of logical syntax.
Furthermore, the schema being defined upfront allows you to mimic the appropriate data structures while developing. Thus, you don't need to rely on further documentation or communication with external developers.
When working with REST APIs, particularly from a front-end perspective, you typically structure the front end along the lines of REST endpoints to retrieve and display data relevant to a single call.
While this simplifies the process, it becomes difficult to implement complex requests and display the relevant information. Furthermore, each endpoint performs a specific operation and thus is at the whim of the created endpoints.
Understanding data is the most fundamental aspect of any system. Without the correct data, you won't be able to accomplish your goals. Only by understanding what data is available and how it relates to other data can you create the necessary logic.
GraphQL is 'strongly typed' and adheres to a strict schema that defines all the methods and data objects you can work with. The advantage of this is that you know the exact rules and possibilities of all the methods and allowed data objects. This will enable you to validate your queries before they are executed and understand the particular structures in more detail. In addition, you're able to mimic the GraphQL server based on these rules, which increases the speed you can get integrating once you've overcome some of the challenges mentioned previously.
Additionally, you receive more detailed information from error messages instead of outright rejections with things such as ‘400 - Bad Request' responses.
Unlike GraphQL, there is no strict schema where one can validate any data objects against. Instead, developers trawl through the relevant API documentation to see what fields and parameters are required for each request. This is a drawback of REST APIs, which can become frustrating, especially when submitting request parameters. With well-documented APIs, this isn't a challenging task; however, the 'back end' rules of things such as the exact format are fields are not displayed, and therefore you need to develop on a trial and error basis to see what formatting works with specific requests.
On the other hand, as mentioned above, when getting started with a particular REST API integration, you can quickly view what data structures that exist on the platform without having to go through all the documentation and specify exactly which fields you need, as you might not have a complete idea of this required information. Due to the drawback of "overfetching", this can actually present an advantage as you can view the full range of possible data fields before starting an integration project. You can then figure out what data you need and the corresponding data structure.
Learning a new skill or toolset is challenging for users, mainly if they aren't highly technically skilled or have the time to commit to learning.
GraphQL requires a much deeper understanding of the data you are working with and learning the necessary syntax to get what you need. This can become frustrating when just starting as you are just trying to see what data you can work with. However, once you've learned this new skill, it can be a powerful asset in your toolset.
The structure of REST requests is relatively simple, and all follow the same structure. As a result, you're able to quickly get working with data structures as responses contain most of the available fields, giving you a much better understanding of what's possible.
A critical aspect that affects your willingness to learn a new skill is the value it will provide. But, of course, much of this depends on how widespread a particular technology is used in the industry.
GraphQL is pretty 'new' and thus is not widely used in the industry (yet) - this will limit what integrations you can perform. However, GraphQL may become more established as time goes on and developers get more familiar with GraphQL and choose to adopt GraphQL for the advantages of optimization; however, this will ultimately depend on external developers' willingness to learn and implement GraphQL queries.
REST APIs are pretty 'mature' and are widely established as the de-facto norm for integrations. If you've done any integrations previously, you would have more than likely encountered REST APIs in various forms. On the whole, REST API adoption has led to robust and well-structured APIs, which enables developers to integrate from one system to another with a lessened amount of time spent learning the ins and outs of the various systems.
The battle in the low-code space
Both GraphQL and REST have their pros and cons in the implementation of integrations. In low-code tools, these advantages and disadvantages take on different forms compared to traditional software development. Low-code tools such as Linx aim to reduce or remove the steep learning curve of conventional coding from application development. However, due to the complexity of GraphQL, it isn't as simple as when working with REST requests.
The main crux of GraphQL is that it is relatively new and requires an upskilling in a new 'language', which goes against the principles of low-code platforms. Due to the query syntax being complex (yet powerful), it becomes time-consuming to learn a new syntax and script your queries out. This complexity of possibilities makes it challenging to implement functionality within a low-code platform that will create the necessary custom queries, which can be as big or as small as you like. While all the validation is taken care of by Linx, you still need to ensure that your queries are correct using an external tool to test, which, as mentioned before, aren't the most user-friendly tools in their current form. GraphQL is complicated, especially to new or less technical users of low-code platforms, which presents a challenge in terms of rapid development. However, suppose you already understand the query language, then executing your queries and working with the resulting data is effortlessly incorporated in the typical low-code fashion of drag and drop.
Due to REST requests having a more simple structure, they are much more usable in a low-code environment for technical and non-technical users alike. Linx makes it easy to execute requests against any REST API with slight tweaks here and there if you want to maintain or extend your current calls. Building a 'library' of API calls to use interchangeably in your logic is reasonably straightforward will save you loads of time. Lastly, the mature nature of REST allows low-code platforms to quickly implement the best practices of consuming APIs inside their tool.
The final say?
In my opinion, I'm going to keep sticking with HTTP requests and build out the various functionalities with modularized re-usable requests until I become more comfortable with scripting out GraphQL queries.
While GraphQL has its advantages, I'm more comfortable with interchangeably using my different requests in Linx to create my types of complex "queries". If I were to replicate them in a GraphQL manner, it would require some syntax learning and scripting out queries, nullifying the inherent advantage of low-code - speed!
While Linx does take care of the nitty-gritty connection details and validations for both, with GraphQL I still need to script out JSON queries by hand, which is time-consuming and can be frustrating if you haven't got them 100% correct.
GraphQL wins if your core focus is performance and optimisation, which is often the case. However, developers should consider the time spent learning the syntax and the level of performance required.
With Linx, rapidly building out libraries of HTTP requests is much easier and faster like described in this recent blog post, so for now, I'll stick with this until the majority of the ecosystem has shifted in favour of GraphQL over REST.
A compromise is rapidly building out your API integrations with REST requests - once you've understood the data you are working with and how this data integrates with your custom logic, then make the relevant migration to GraphQL.