What Is GraphQL? Does It Reduce the Need for Documentation?

  • Fri, Jan 4, 2019
  • 3-minute read

What is GraphQL?

GraphQL is a query language created by Facebook in 2012 and made it open source in 2015.

The API ecosystem has been dominated by REST APIs for a while, but RESTful APIs have certain constraints that made Facebook come up with a different approach while handling requests that were four or five levels deep in other person’s network.

Just like REST, GraphQL is used to communicate data between a Client and a Server.

clientserver

But the main benefit of using GraphQL is that you can ask for exactly what you want, and you get those results and nothing else.

REST vs GraphQL

RESTful APIs and GraphQL have some things in common and some important differences.

  • They are both specifications for building and consuming APIs
  • They can both be operated over HTTP, though GraphQL is protocol agnostic

One of the major differences is that with GraphQL, you only have one endpoint. With a single request, you can get an object and its related objects, while in REST you have different endpoints that can access different resources which means that if you need data from different resources you have to make different calls, each of them returning complete objetcs probably with data you don’t even need.

restvsgraphql

How does GraphQL Work?

To have a GraphQL environment, you need:

  • A Base Server, where you run the base code of your GraphQL environment.
  • A Schema, which consists of:
    • Queries, which define what data returns the server when you make a query. The response has the same shape as the query.
    • Mutations, which are GraphQL’s way of creating, updating, or deleting data.
  • A Resolver, a function that responds to queries and mutations and gives you the result.

The Schema is the shape of your data. When you define your schema, you’re defining how the data will be and what type of data it can expect.

The Schema defines the query Type and the Resolver for each API input. The type definition provides what type of data we expect and the resolver gets the data.

Everything in GraphQL is defined by types. Like in any JavaScript object, inside of it you have the fields and then declare what type of data you expect for this field.

GraphQL accepts basic data types such as:

  • Int Integers
  • Float Floating numbers
  • String String of characters
  • ID Unique Identifier numbers
  • Boolean True or False values
  • ENUM Which define specific sets of data

Does GraphQL Reduces the Need of Documentation?

GraphQL comes with an interactive feature –GraphiQL– that allows to play with the API to see the available relationships by typing the queries or by exploring the Docs section.

graphiql

But, even though GraphQL’s built-in Docs feature and interactive querying are effective and functional for developers, they are not enough.

The need for real documentation remains for:

  • On-boarding.
  • Getting started (guides, tutorials, etc.)
  • Reference documentation for PMs, stakeholders, etc.

When documenting a GraphQL API you need, at least:

  • Overview or Getting Started section, which must have the following information:
    • Endpoint
    • How to make a request to the GraphQL API endpoint
  • Authorization process
    • Reference
    • GraphQL schema
      • Queries
      • Mutations
      • Types

These are some examples of GraphQL documentation that you can check out if you need some inspiration:

documentationgraphqlapiapi documentationtechnical writing