As APIs have become more important it is crucial to offer flexibility in their use. REST API has been the dominating architectural style over the past two decades. With the API Gateway and other improvements, it has been able to keep pace with the ever-changing customer demands. Novel approaches such as the Graph API offer such features as a native property of their design philosophy. They offer benefits to API consumers and providers which are still not understood in full. In this paper we explore Graph API, how it works, performs, and what are the differences between it and the standard REST API. We experiment and assess the performance of GitHub, GitLab and Star Wars APIs in REST and Graph forms. Conclusion is that neither approach is ideal in all situations, but they supplement each other where the other falls short.
Scholar. To understand performance differences, we test three well-known APIs in both REST and Graph forms. Answers are elaborated on in Chapter 4 of this paper. In Chapter 3, we will look at the lessons learned from our research and our experiment. Specifically, focusing on the differences between two approaches, the performance they offer, and how it is perceived in testing Chapter 2 offers a baseline on REST API principles and goes into more detail on the novel Graph API approach, including how it is made up of schemas and how to formulate a request. We by no means offer a comprehensive guide on how to design production-ready Graph APIs, but rather an entry point into a new principle. We also explore the current industry players offering Graph APIs.
There has been an attempt to quantify the performance benefits of Graph APIs. Previous works
have addressed different aspects of the design approach. The work of Eunggi, Kiwoong, and
Jungmee [
Both REST API and Graph API approaches aim to accomplish the same goal: to provide clients with requested data. To better understand them, we will first present how each provides services to customers and some of their key principles. At the end of this section, we will also discuss some of the key players that are in the market for providing Graph APIs.
In his thesis, Roy Thomas Fielding first coined the term "Representational State Transfer (REST)
as an architectural style for distributed hypermedia systems. REST provides a set of architectural
constraints. When applied, the constraints emphasize scalability of component interactions,
generality of interfaces, independent deployment of components, and intermediary components
to reduce interaction latency, enforce security, and encapsulate legacy systems. [
Among these, the first is the most fundamental to a RESTful API. Providing a uniform interface is the basis on which the API is built. It should adhere to the following constraints: identification of resources, manipulation of resources through representation, self-descriptive messages, and hypermedia as the engine of application state (HATEOAS).
This then brings us to how we expose our data over such interfaces. Every resource has its
own Uniform Resource Identifier (URI) that corresponds to an exposed Uniform Resource
Locator (URL) [
One of the remedies has been to implement patterns via the API Gateway. These patterns allow
us to abstract how our APIs are connected between themselves and provide use-case-driven APIs.
Some of the patterns include the API Facade, API Composition, Two-phase Transaction
Management and Synchronous to Asynchronous Mediation [
Another undefined area with REST is its service description. It’s now been standardized with the Open API initiative, but there are still many tools that go about generating the description. Swagger, as viewed in Figure 1, is one such tool. It offers us a description of a basic parking service. What endpoints does the API respond on and what are the HTTP methods for achieving them? From the figure, we observe the four basic verbs. GET, which is used for fetching resources. POST for creating them, PUT for updating them, and DELETE for deleting them. There are other verbs such as HEAD, TRACE, PATCH, OPTIONS, and CONNECT that are less commonly used.
In the next chapter, we’ll present how the Graph API handles these areas.
Graph API offers an alternative to the REST approach to building APIs. Graph Query Language
(GraphQL) is a query language that produces APIs that facilitate flexible access to data. Although
using GraphQL is not necessary to provide a Graph API, it is often the case. One of the key
advantages Graph APIs have over REST APIs is that clients receive only relevant data and can
create new queries that suit their needs without any changes on the backend [
Now that we have a simple schema, we may look at how we can extract the data from an API that
would be exposing its data over it. In Figure 3, we now see a query and a mutation being
formulated. It is only valid because of the schema we have defined. The query would only return
the names of rooms in the building with an id of 123. The mutation would create a room with the
name "Living room" and give us back the ID it was created with. Why GraphQL is so intuitive for
clients to adopt is the ability to introspect the schema behind the API. This also allows developers
to build tools around it, as intelligent suggestions can be made about the API itself at runtime
[
These requests are normally enveloped in the body of a POST request. Although there is
precedent for mapping certain requests as GET parameters, there are certain limitations to this
approach, but the benefits of keeping the API discoverable sometimes outweigh them. Facebook
is the creator of GraphQL, and they are using GET for most simple requests that do not require
complex queries [
As Gartner has pointed out, Graph APIs are in the Innovation Trigger stage [
The key differences in the two approaches to API design that stand out are the philosophies in which the challenges of request performance are addressed. The REST API is usually quicker in providing responses, but they are less tailored to the needs of the customer. It also requires clients to know where certain resources are available. Graph API, on the other hand, exposes a singular endpoint and accepts requests via a query in the body of a POST request.
With the REST API, to find the repository information from which we can extract the collaborators, we must visit the following endpoint: https://api.github.com/repos/{owner}/{repo}/collaborators. The {owner} is replaced by the username of the owner, and the {repo} is replaced by the name of the repository we wish to visit. We are presented with a full array of collaborators and 25 fields for each of them, visible in Figure 4. Among them, only two of them are relevant to our needs. This illustrates one of the common problems with REST, as we have no way of applying specificity to our request. It leads to acquiring more data than is necessary for our given needs. What is worse is the fact that this endpoint does not include all the user data but only a subset that the provider decided to include. There is no bio field for a user. This is the problem of "under fetching," where the endpoint does not provide all the data needed for our use case. To obtain this data, we must visit another endpoint, https://api.github.com/users/{user}", where the {user} is replaced with the user we wish to query. Where we are again served with 32 fields, of which only one is relevant to our use case. If we are authenticated with a token from the same user, the number of fields is 43. This is the problem of "overfetching" more data than needed.
Graph API gives us the tools to specify exactly the fields we wish to extract from it. Not only is it available, but it is also mandatory. This could lead to APIs being prohibitive for new developers to adopt. But since the schema is a mediator with its introspection, it allows developers to easily discover which fields they may call. In the Graph API, with a single well-defined query in the body of a POST request, we are presented with a tailored response of only the needed data. Giving the client the power to design a desired response from the API. Such is evident from Figure 5, whereby, by specifying the "login", "bio", and "url" fields, we are presented only with those. Fetching exactly the data we need.
The key differences in the two approaches also lead us to believe there are performance differences. To evaluate our hypothesis, we have devised several test scenarios on platforms where APIs are available in both REST and Graph forms. Based on real use case scenarios presented in Table 1. We performed tests for all scenarios were using Apache JMeter with settings observed in Table 2.
Settings remained the same across use cases, except for UC2 and UC3 at GitHub where we increased the ram-up period to 10 minutes to spread out requests over. We did this due to rate limiting and we were not able to perform more than twenty requests in succession. We assume this did not impact our results as the aim was not to test load capabilities of GitHub or GitLab APIs. Regardless, our aim was to collect the following metrics: • Average, minimum, and maximum response times and their standard deviation (milliseconds) • • •
Size of response (bytes) Size of request (bytes)
Throughput (requests per second) – only Star Wars API
In the case of the Star Wars API, we were able to stress the system because it was a self-hosted instance in a Docker container on a VirtualBox virtual machine with resources listed in Table 3. Hence, we also collected the throughput of the requests.
Results are visualized in Figure 6a, presenting our findings for response times on all three APIs and throughput on the Star Wars API. In Figures 6b and 6c, we skewed the standard deviation visualization for Graph on Use Case 2. This was done because the results were making other results difficult to read and interpret. Actual numbers for standard deviation are 3120,84 and 9759,93.
In Figure 6, we observe that in the case of GitHub and Star Wars API graphs, the more
performant option is faster to give requested responses. Although in the case of GitHub, it is worth
mentioning that the two REST requests were individually faster than graph, we required two of
them to achieve our use case. It also stands out that graph was usually the more consistent choice,
resulting in a lower standard deviation in all but a few use cases. Which runs counter to what a
related study found [
The next surprise came in the form of Graph being better behaved under moderate load. When a system has limited resources and REST requires more requests than graph, it can result in severely degraded performance. Which is nicely presented in Figure 6d, where the difference in simple queries is minor and very big when REST requires just one more request per resource.
In this chapter, we will address the research questions presented in the introduction. We will answer them with the knowledge we have acquired from literature and our experiment.
The key difference between the two approaches is that Graph provides a singular endpoint where
it accepts requests in a POST body. However, for simpler queries, GET can still be used. REST
presents different endpoints that are more tailored to the use cases of an application. Which does
have its benefits, but the main drawbacks are the over- and under-fetching of data. The amount
of data we retrieve from the server is predetermined by its developers. Graph gives that power
of decision-making to the user. Which can be a great thing when we are exposing a large API with
related data to the public. As maintainers of an API, it is utopian to foresee and prepare all use
cases, and even more so to maintain all those endpoints. One of the challenges Graph API provider
faces is limiting how much data users can extract from it. Due to the interconnectivity, it is crucial
to implement the cursor pattern and enforce limiting numbers of entries per request [
REST API providers have been addressing this issue with the advent of API management platforms. These platforms allow us to create use cases from APIs, compose them with no code, and expose and version all these endpoints with ease. This gave the REST API the API Gateway pattern, which has essentially the same goal as a graph API's native feature: to provide a singular point of access to our API.
As we have discovered in Section 3.2, no approach is indefinitely better than another. There are
situations where one is preferable to the other. When we need simple resources presented
quickly to the customer, REST appears to be more effective. The responses were usually quicker
than those of the Graph counterpart. But if we require more complex queries that require
combining more endpoints, Graph appears to be the more efficient option. There also seems to
be a difference in how much computational power each API requires. Graph trades a more
process-heavy server for a leaner client with less required bandwidth. This leads us to believe
that the Graph API is more processor-intensive than REST since it takes more time to traverse a
graph than to simply respond with a pre-prepared query in REST. Although it has been shown
that Graph is more efficient than REST in the utilization of its resources [
Graph API also liberates the client from having to process received data, shifting the responsibility from the client to the server. This also results in lower bandwidth requirements, as less data is transferred overall.
In testing, we experienced no considerable differences in performance, load, or stress testing with JMeter. It requires a different approach to payload transfer setup and transferring more data to the server via the larger request body. In unit testing, there should be no perceived differences between the two approaches. However, Graph could turn out to be more friendly to developers when it comes to preparing JSON strings to compare responses to, as they are leaner and more focused on the data we wish to retrieve and test.
In Table 4, we can see the key differences between two approaches to APIs. Both are flexible and replicate each other in the definition of the service, and they both support the same key CRUD (Create, Read, Update, and Delete) operations. Although the Graph API is not cacheable, its resource utilization and customizable response make it better performing. Both approaches are testable in the same way, although a different philosophy in forming the request is dictated by the API type. Even so, REST remains the industry standard.
We have conducted an exploratory study of the Graph API and how it compares to the REST API in key areas of conceptualization, performance, use cases, and performance testing. We can draw conclusions from the works of previous authors and add our own experiment. We conclude that REST and Graph API both have a place in the industry as complementary principles. This is further supported by the fact that some providers offer both API options. It is worth mentioning that the Graph API has an edge when working with larger, interconnected data sets that are exposed to the public, where use cases are hard (and numerous) to predict. It also alleviates the pressure on client devices in terms of computational power and required bandwidth. REST, however, remains a better option when we know the use cases of our customers and it is feasible to prepare them beforehand in more closed and controlled environments.
We suggest the following areas for further research: When does the Graph API become better in terms of performance to warrant the extra expense of computational power? How interconnected must the data be to make use of the relationship-focused approach of the Graph API? When do use-case generation tools like API management platforms cause bigger expenses than the additional computational power of Graph APIs? In this paper, we have limited ourselves mostly to the performance analysis of retrieving data from the server.
The authors acknowledge financial support from the Slovenian Research Agency (Research Core Funding No. P2-0057).