REST and (the newer) GraphQL APIs are the core technologies behind most of today’s integrations. These APIs allow external developers to tap into the major platforms’ functionality and build 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:
- Learning curve
- Working with data objects
- Industry adoption
Let’s get started;
GraphQL wins this debate on performance and optimisation. 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 strong point 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 challenges meeting API request limits, bandwidth usage, and overall system optimisation. However, this might not be an issue depending on how much data you are processing. 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 bandwidth usage.
Additionally, REST endpoints suffer from two issues in terms of data retrieval, namely
Underfetching: Endpoints return only a subset of the information that you require. Unfortunately, this leads to the scenario where you need to execute several subsequent requests to retrieve the complete data set. Depending on the API and your specific needs, this can enormously impact optimisation and scalability, so it always needs to be kept in mind.
Overfetching: 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 behavior 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, 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 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 are ‘GraphQL Explorers’ such as GraphiQL, which makes 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 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 delving into the particular fields of each response and determining 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 need to understand the codebase to maintain the system.
GraphQL queries are written in a syntax that is not entirely obvious. Therefore, when creating large and complex queries, you may want to re-use them slightly differently, either re-writing the whole query out again or copying the text and tweaking it in the various locations within the query itself. Unfortunately, this process slows development and 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; 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, GraphQL is a query syntax, so 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 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.
Working with Data Objects
Understanding data is the most fundamental aspect of any system. Without the correct data, you won’t be able to accomplish your goals. You can create the necessary logic by understanding what data is available and how it relates to other data.
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 can mimic the GraphQL server based on these rules, increasing the speed you can get integrated 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 which 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 ‘backend’ 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 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 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 can 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 progresses and developers become 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, enabling developers to integrate from one system to another with less time spent learning the ins and outs of the various systems.
The battle in the low-code space
GraphQL and REST have their pros and cons in implementing integrations. In low-code tools, these advantages and disadvantages take different forms than 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 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 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.
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, make the relevant migration to GraphQL.
Low-code API development guides
- Design-first using an OpenAPI specification
- Code-first API builder, fast implementation, including hosting and documentation