APIs
7
min of reading
January 3, 2018

The Ascent of GraphQL in the Age of APIs

Daniel Varanda
Responsible for deep architecture discussions with customers to ensure solutions designed for success based on customer needs.
More about the author

APIs

APIs are on the rise, mainly in companies that are not digital in their nature of business. This context includes banks, financial companies, insurance companies, payment media companies, retail companies, etc. Companies are seeking to make the experience of their consumers more digital and with fewer human interactions, and APIs are a great enabler for digital strategies.

But, after all, what are APIs?

An API (Application Programming Interface) is a set of routines and standards established by software for the use of its feature by applications that do not aim to be involved in implementation details, but only use their features.

Examples include RMI, JMS, and positional file exchange.

Web API is one of the possible ways to build APIs, in which the exchange of information between applications is carried out through the Internet (more specifically, through HTTP).

Examples include WebService SOAP, RESTful, and GraphQL.

RESTful API

Before talking about GraphQL, we will talk address difficulties encountered in the RESTful standard, which have caused the great ascent of the use of GraphQL for building APIs.

In RESTful, the features of APIs are accessed from a URI, which interacts with Resources and Elements through the HTTP Methods.

Imagine that we need to build an application in which all our Facebook friends who “liked” Sérgio Moro’s page (the judge responsible for one of the largest anti-corruption proceedings in Brazil) are obtained.

How would that query be made if Facebook had only one API in the RESTful standard:

  1. Make a request at:

GET: http://api.facebook.com/me/friends

2. Now, for each of the “N” returned friends, a request should be made at:

GET: http://api.facebook.com/me/friends/{friend_id}/pages?page_name=Sérgio Moro

Depending on the number of friends you have, it may be necessary to make the request hundreds or thousands of times.

When the APIs are intended for internal use, it is possible to perform a workaround (as in the previous example) to solve certain problems.

That, however, is not scalable!

  • It demands specific (or case-by-case) implementations
  • Greater development time
  • New resources to maintain
  • Many other drawbacks

In an Open API strategy, as is the case with Facebook APIs, it is impossible to predict all the needs that application developers will have regarding the APIs. Therefore, it is important that application developers have the autonomy and freedom to use the APIs in a much more flexible way than enabled by the RESTful standard.

GraphQL API

  • GraphQL is a Declarative Query Language
  • A specification for client/server interactions
  • Data store-independent
  • Platform-independent
  • Traffic over HTTP protocol
  • Developed in 2012 by the Facebook and Open Source team since July 2015
  • Mainly used to improve the performance and experience of using Mobile applications

Normally, it only uses one endpoint / graphqlFacebook mobile applications have used the GraphQL API since 2012. Since becoming Open Source in 2015, many other devices of all sizes are also using GraphQL:

And many others…In a simple and summarized way, to perform a “hello world” in GraphQL, the following is necessary:

Describe your data

type Project {

name: String

tagline: Stringcontributors: [User]

}

Inform what you need (request)

{

project(name: “GraphQL”) {

tagline}

}

Obtain the result (response)

{

“project”: {

“tagline”: “A query language for APIs”

}

}

GraphQL-Server is where the GraphQL API implementation is performed. At the run time, GraphQL-Server has the following responsibilities:

  • Validation: determining if the Query or Mutation is valid or not.
  • Solve: specifying where the data will be obtained.
  • Producing the result: treating each attribute to produce a payload that reflects the query made.

The image below shows what the use of a GraphQL API is like.

Note that in each request to a GraphQL API:

  • The request will always be made in the same URL and using the same HTTP Method (POST method), irrespective of the data being requested or controlled. E.g. POST: http://api.sensedia.com/graphql.
  • The response will always be an “HTTP 200: OK,” irrespective of whether the result of the request has been successful or in error.

In GraphQL, it is possible to perform data Queries and Mutations (data alterations).Queries – Analog to Restful’s GET operation.

Declarative query language

The client informs the data it needs, and the answer is a mirror of the request.

Allows multiple queries in the same request

GraphQL-Server executes the queries in parallel to optimize the request.

Merging of the same object instance

Alias

Avoiding conflicts between different instances of the same object.

Nested objects

Cyclical references

Arguments

Each attribute and nested object can have its own set of arguments.

Pagination

Variables and Directives

Fragments

Unions and Polymorphism

Situations in which you do not know the type of return and you need to determine somehow how to process that data in the client.

Mutations

It is analogous to the POST / PUT / DELETE operations in Restful.

While the Queries are executed in parallel, the mutations are executed in series, one after the other. This means that, when sending two “Credit Implement” mutations, the first one will end before the second one begins.

If the mutation operation returns an object, you can request specific attributes and nested objects.

Validations

GraphQL in a few words

  • A unique endpoint
  • A Query Language for your API
  • Ask for what you need and get exactly that (nothing more, nothing less)
  • Obtain many resources in a single order
  • Describe what is possible with a typing system
  • Move faster with powerful developer tools
  • Evolve your API without the need for version control
  • Use your own databases and code

Attention points

  • Operations are not clear as in REST (GET / POST / PUT / DELETE)
  • All returns are “HTTP 200 OK”
  • More power for APP developers
  • Does not facilitate the side of providing the APIs
  • Side effect of using more input data in the request and server use (processing)
  • Does not solve only design problems (effort)
  • Difficulty in troubleshooting problems and supporting app developers

Suggestions and best practices

  • Use first for internal APIs or for restricted external use.
  • Use it to improve app experience / performance that consume data from backends.
  • Be careful when exposing it the world (Open APIs). Do not allow arbitrary (uncontrolled) queries from unknown clients.

GraphQL Ecosystem

GraphQL Clients

  • JavaScript – Relay, Apollo Client, Lokka
  • Swift / iOS – Apollo iOS
  • Java / Android – Apollo Android
  • C# / .NET – graphql-net-client

Server Libraries

  • JavaScript – GraphQL.js, express-graphql, graphql-server
  • Ruby – graphql-ruby
  • Python – Graphene
  • Scala – Sangria
  • Java – graphql-java
  • Clojure – alumbra, graphql-clj, lacinia
  • Go – graphql-go, graphql-relay-go, neelance/graphql-go
  • PHP – graphql-php, graphql-relay-php
  • C# / .NET – graphql-dotnet, graphql-net
  • Elixir – absinthe, graphql-elixir

IDE to Document and Explore GraphQL APIs

GraphiQL – https://github.com/graphql/graphiql

Thanks for reading!