Switching from REST to GraphQL

Less code, more readability. It sounds easy but it isn’t when you are creating an API. Before the revolution of GraphQL, REST was the first option when you needed to create an API (also there was the SOAP option but as developers and companies were migrating from SOAP to REST, they found this was a big challenge given the thousands of lines of code and high level of complexity in some cases).

REST was the solution to a lot of the problems that SOAP had, like:

• Variety of data formats (SOAP just offers XML)
• Ease of use
• Performance
• Complexity
• Learning curve

API request flow representationBut in some cases REST showed certain problems too and they turned out to be the reason to reconsider REST as an alternative. Two of the reasons are: the amount of code needed to represent a single entity, without adding the relationships that the entity has, while also the amount of endpoints needed to expose all the resources.

Here is where GraphQL brings a solution to those known issues in REST, but what is GraphQL?

GraphQL logoGraphQL is a query language for APIs and a server side runtime that executes the queries. GraphQL is not the typical library that is tied to a specific language or database, as you can use it in any programming language. GraphQL was created in 2012 by Facebook. The first public version was launched in 2015 and the first stable version in 2018.

A basic GraphQL service structure is composed of types and fields with functions for each field and each type. It might be confusing at first but you’re going to see how powerful this technology is.

The following example helps illustrate how it works:

type Query {
  person: Person
}
type Person {
  id: ID!
  name: String!
}

function Query_person(request) {
  return request.args.user;
}

function User_name(user) {
  return user.getName();
}

After the definition and implementation of the service, it can receive query requests like this:

{
  person {
    name
    id
    age
    height
  }
}

Here is where GraphQL makes the difference; because you can request just the data that you need, there is no need to request an entire object like you would typically do when using REST. In this case we request the “id” and the “name” of the person.

The result looks like this:

{
  "person": {
    "id": "122394",
    "name": "John Doe"
  }
}

That’s not all: you can also create other types of functions not to just get data from the server, but also to create and edit data that already exists. There is a special type for that called mutations. Mutations can also return data and you can request any field or nested field required by the front end.

This is an example of a mutation:

mutation CreatePerson($person: Person!) {
  createPerson(person: $person) {
    age
    name
  }
}

The result for that mutation looks like this:

{
  "data": {
    "createPersonn": {
      "age": 25,
      "name": "John Doe"
    }
  }
}

Based on the structure of the object that we return on the server side, we can ask for more information related to the Person entity and also the entities tied to this, in a single request,. This is a huge advantage because we consume less resources and improve the performance of the application.

There is much more than that in this library, like the use of fragments, interfaces, inputs and other great features that you can use. Here you can find more information about it.

Now, why should I move my REST API to GraphQL? Is it really a good idea to move from one technology to a new one?

I’m not saying that REST is going to disappear right away but it could be more expensive to migrate to GraphQL in a few years, not just in terms of money, but in the resources needed as your code can grow really fast and that increases complexity, readability and maintainability.

These are some of the advantages that GraphQL has over REST:

• No underfetching: while REST needs more than one request to get data from 2 different entities, GraphQL can get data from more than 2 related entities, why? Because the way that it’s built allows you to create queries with nested data from other entities.
• No overfetching: you can get just the information that you need, which means that you can request just for one property or all of the properties for a specific entity.
• Less code: since there is no need to create more than one endpoint, your code gets more clear and less code is needed to solve requirements and tasks.
• Schema and type system: GraphQL uses the schema as a contract between the client and the server on how the client accesses the data. Also the type system helps to create the capabilities of the API, there is a Schema Definition Language (SDL) where all the types are defined.

Migration, however, is not the only option. There is also the option to combine these two technologies. You can still have the REST API and make requests using a middleware created in GraphQL. This is a good option to improve the performance of the application, since the middleware will be in charge of the parsing of the data returned from the API and then you just get the data needed to present in the application. It also allows your teams to start working on building the GraphQL queries and using its framework to later make the migration a lot easier, if that’s the route you decided to take.

Conclusion

There is much more that can be compared between these 2 technologies. This article just gives a small intro of what GraphQL is and how it can improve performance over REST. The power of this technology is huge and will continue growing in the upcoming years. Like with most technologies, there is no magic trick to migrate from GraphQL to REST, the learning curve can be tricky but it will prevent future issues and will improve performance, readability and maintainability of your application.