API Development: Rest Vs GraphQL

Source: codingthesmartway

What is REST?

REST (Representational state transfer) is an architectural pattern that defines a set of constraints to be used for creating Web services. A RESTful API (RESTful web service or REST API )— is built out of the representational state transfer (REST) technology.

A RESTful API is an application programming interface (API) that uses HTTP requests to GET, PUT, POST and DELETE data. With cloud use on the rise, APIs are emerging to expose web services. REST is a logical choice for building APIs that allow users to connect and interact with cloud services.

What Is GraphQL?

GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data. GraphQL provides a complete and understandable description of the data in your API, gives clients the power to ask for exactly what they need and nothing more, makes it easier to evolve APIs over time, and enables powerful developer tools. GraphQL is also an open-source technology. GraphQL was developed by Facebook in 2012 for internal development but later went public in 2015.

Difference between REST and GraphQL

• Similar: Both have the idea of a resource, and can specify IDs for those resources.
• Similar: Both can be fetched via an HTTP GET request with a URL.
• Similar: Both can return JSON data in the request.
• Different: In REST, the endpoint you call is the identity of that object. In GraphQL, the identity is separate from how you fetch it.
• Different: In REST, the shape and size of the resource is determined by the server. In GraphQL, the server declares what resources are available, and the client asks for what it needs at the time.

NOTE: REST APIs have become the de facto standard for companies deploying APIs and launching developer platforms. The beauty of REST is that a developer working with someone else’s API doesn’t need any special initialisation or libraries. Requests can be simply sent via common software like cURL and web browsers.

REST and GraphQL(PROS/CONS)

1. Data Fetching

Let’s assume I want to build an app that displays a blog author information. I want it to display the name of the author and the blog posts written by the author and the three most recent blog topics written by the author.

REST

In Representation State Transfer (REST), we call an endpoint, to request the data that we need. The server then responds back with the response:

/blog/author/<id>

This endpoint would fetch the author’s information. I would then need another endpoint to access the blog posts.

/blog/author/<id>/posts

And finally I would need another endpoint to get the blog topics.

/blog/author/<id>/topics

CONS: Multiple network calls — REST

You are to make typical number of network calls queries while using REST to get the data that you need. REST endpoints get out of control, as our data needs to expand. This leads to multiple network calls and causes a slowness in response time.

Over-fetching and Under-fetching Problems with REST

Often with REST, you will end up with data that you don’t need. For example, when calling the blog/author/<id> endpoint, you will get all the data pertaining to the author. You could get back data like, date_created, date_updated, age, gender and so on. But all we needed was the author’s name. This is a classic example of over-fetching in REST.

In the case of under-fetching, you can notice here that just the call to blog/author/<id> was not sufficient to retrieve what we are looking for. To get the last three posts written by the author, we had to make a call to another endpoint blog/author/<id>/posts. This situation is called under-fetching.

GraphQL

Guess what happens when using GraphQL ? You write one query to ask for what you want, and you get back exactly what you asked for.

There are no multiple network calls in order to fetch data in GraphQL

This will make more sense if you see the actual query and the response received.

GraphQL Query Request

This is how our query will look like. We pass in the fields that we need response for. We are looking for the author’s name, last three blog posts written, and the last three topics they wrote. The query is structured to ask exactly what we need.

{
  author (id: 6) {
    name 
    posts (last: 3) {
      title
    }
    topics (last : 3) {
     name
    }
  }
}

GraphQL Query Response

Here is what we get back from the server.

{
  "data" : {
    "author" : {
      "name" : "Adhithi Ravichandran",
      "posts" : [
        { title: "React vs. Vue : A Wholesome Comparison"},
        { title: "React Lifecycle Methods: A Deep Dive"},
        { title: "5 Essential Skills A Frontend Developer Should Possess"}
      ],
      "topics" : [
        { name: "React and Vue"},
        { name: "React"},
        { name: "General"}
      ]
    }
  }
}

GraphQL: No multiple rounds trips to server, no over-fetching and no under-fetching of data.

2. Rapid Product Development On Client Side

While using REST APIs, client teams that are using the APIs tends to wait for the backend team to complete their development of APIs, to start using them. Often, the frontend team sees slowness in development because of this prolonged waiting for APIs from the backend team. I have been a part of this situation several times, where the frontend developer’s hands are tied until the backend hands over a working version of their API.

This leads to slowness in development, and a huge reliance on the backend team to deliver faster so that the client team can start their work to consume the API.

In the GraphQL, there is a parallel development for both the front, backend or any other client, without stalling the development.

GraphQL: Teams work in parallel, leading to rapid product development

The frontend teams can work with mock versions of the API, and also use libraries like GraphQL Faker to create fake data. Coding can be completely done with mock data and tests can be written too. When the backend team is ready with the APIs, the mock API can be switched with the real API.

CONS Of GraphQL

Caching

Caching is built into in the HTTP specification which RESTful APIs are able to leverage. GET vs POST semantics related to caching are well defined enabling browser caches, intermediate proxies, and server frameworks to follow. The following guidelines can be followed:

• GET requests can be cached
• GET requests can stay in browser history
• GET requests can be bookmarked
• GET requests are idempotent

GraphQL doesn’t follow the HTTP spec for caching and instead uses a single endpoint. Thus, it’s up to the developer to ensure caching is implemented correctly for non-mutable queries that can be cached. The correct key has to be used for the cache which may include inspecting the body contents.

While you can use tools like Relay or Data loader that understands GraphQL semantics, that still doesn’t cover things like browser and mobile caching.

Exposed for arbitrary requests

While a main benefit of GraphQL is to enable clients to query for just the data they need, this can also be problematic especially for open APIs where an organisation cannot control 3rd party client query behavior. Much concern has to be taken to ensure GraphQL queries don’t result in expensive join queries that can bring down server performance or even DDoS the server. RESTful APIs can be constrained to match data model and indexing used.

Rigidness of queries

GraphQL removes the ability for custom query DSLs or side effect operations on top of an API. For example, the Elastic search API is RESTful, but also has a very powerful Elastic search DSL to perform advanced aggregations and metric calculations. Such aggregation queries may be harder to model within the GraphQL language.

Non existent monitoring

RESTful APIs have the benefit of following the HTTP spec with regards to resources just like a website. This enables many tools to probe a URL. For GraphQL APIs, you may not be able to leverage such tools unless you support placing the query as a URL parameter as most ping tools don’t support HTTP and request bodies.

Besides ping services, there are very few SaaS or open source tools that support API analytics or deeper analysis of your API calls. Client errors are presented as a 200 OK in a GraphQL API. Existing tools that expect 400 errors will not work so you may miss errors happening on your API. Yet at the same time, more flexibility given to the client requires even more tools to catch and understand problems with your API.