Consuming GraphQL APIs for REST-minded Developers
Tags: graphql, webdev, tutorial
Published: 2022-01-14 20:11:00

If you've been developing against APIs for more than just a few years, I'm willing to bet that you've encountered and used [RESTful-style][restful] APIs. Why am I so confident? Because REST has become the de-facto standard, most commonly used style of API on the web today. Even though REST is great and has become ubiquitous, it's not without a few challenges and shortcomings:
- Under-fetching data you need
- Over-fetching data you don't need
- Many endpoints - usually 1 for each resource type
- Related data requires multiple calls
- Difficult discovery and auto-tooling
- ...and more

To solve these and other issues, GraphQL was developed by Facebook starting in 2012. It was originally internal-only, but was open-sourced in 2015 and since then it has gained immense popularity. A [recent study][recent-study] indicated that it is used in nearly 20% of all organizations with an API. This may not sound like a lot&mdash;especially when compared to REST's roughly 82% usage rate&mdash;but [another study][another-study] shows that developers' experience with GraphQL grew from around 5% in 2016 to nearly 40% in 2019. That's some solid growth, and Anvil has contributed to those statistics. While we have some RESTful APIs, we rely heavily on GraphQL for the majority of our exposed capabilities.

Yet despite the significant and rapidly growing share of GraphQL APIs out there, some developers who are used to RESTful APIs have yet to use it, and some are reluctant to try and learn it. I'm here to show you that consuming a GraphQL API is really nothing to be afraid of, and it’s something that any developer can figure out the basics of.

### GraphQL Background / Primer

First off, if you have no idea what GraphQL is about and what it feels like, I'd like to suggest a few things:

1. Read [this article][this-article] to help gain a reasonable background on what GraphQL is all about.
1. Try playing around with some live queries in [this online demo][online-demo] to get the feel for how things actually work. Take note of how you can traverse the relationship graph of objects from the root object, retrieving nested/related objects of your choice. Also notice how you can request as much or as little information as you want from each of those objects.

Hopefully after familiarizing yourself with some basics of interacting with a GraphQL API, you realize that for simple queries it's very straightforward. Here's a quick cheat sheet on what you need to know:

- Instead of multiple "endpoints" that you might have in a REST API, a GraphQL API has just a single endpoint, but additionally defines and exposes any number of Queries (for read operations) and Mutations (for insert/update operations). These operations are hopefully given helpful, descriptive names like `invoices` or `updateUser`, etc.
- GraphQL is all about [Types][types], and each operation will normally return an object of a specific Type. These Types include some basic [Scalars][scalars] like `Int`, `String`, `Boolean`, but custom Types built from scalars or even other custom Types can also be defined - think `User`, `Organization`, `Invoice`, etc. These custom Types typically are objects that contain 1 or more [Fields][fields], each of which has a Type.
- [Field][fields] definitions not only require a Type specifier, but they also can have a few modifiers:
  - `!`: A non-nullable (i.e. "required") value can be indicated with a `!`. E.g. `name: String!`.
  - `[<Type>]`: An array of values can be indicated by surrounding a Type in brackets. E.g. `names: [String]`.
  - These 2 modifiers can be combined arbitrarily, for example to indicate "an array of non-nullable Strings" (e.g. `names: [String!]`). Or to indicate "an array of non-nullable Strings, which itself cannot be null" (e.g. `names: [String!]!`).
- The last big thing to mention is that GraphQL supports [Arguments][arguments] for Queries (e.g. the `invoice` query expects an `invoiceId` argument), Mutations (e.g. the `createUser` mutation expects `name` and `email` arguments) and also Fields (e.g. the `addresses` field on a `User` type may accept a `country` argument for filtering).

And with that, while there are definitely more advanced things one can learn about GraphQL, you should be armed with enough knowledge about the [GraphQL spec][spec] to understand how to use and consume most GraphQL APIs.

### Request Shape

Hopefully by now you're no longer mystified by interacting with a GraphQL API, and are starting to see some of the advantages of it. All that's left to do now is actually write some code that consumes one! GraphQL is so popular that there are client packages available in [every popular language][clients] like Node, Python, Ruby, Java, Go, and more. Chances are that whatever language you're using to consume REST APIs has a library to make it easy to consume GraphQL APIs.

If you're unable (or unwilling) to add more dependencies to your code base, or you'd just like to "roll your own" client for whatever reason, I'll show you some examples of how easy it is a bit later on. What I hope you'll realize is that at the end of the day, a GraphQL API call is just a `POST` request to the server's GraphQL endpoint with a JSON payload consisting of a few key/values:
- `query`: A string containing the query or mutation you'd like to execute.
- `variables`: A [JSON object][json] whose keys match the name of any variables used in your `query`, and whose values are the values for the server to use for those variables.

Most servers will even let you send those key/values as [query params to a `GET` request][params-as-get] if you really want to for some reason.

The response should come with a `200`/`OK` status (***even when there are errors***), with a `content-type` of `application/json` and have the following JSON structure:
- `errors`: An array that should be present and populated only if there were errors encountered. The elements in the array should provide details about what thing or things went wrong. As noted above, the server response will still be `200`/`OK` even if there are errors.
- `data`: A JSON object containing the result of your query or mutation operation.

### Sample Code

Hopefully this sounds easy so far, but let's see how it looks in code. Let's say we have a relatively simple `User` query that looks like this:
```graphql
query User($id: Int!) {
  user(id: $id) {
    id
    email
  }
}
```
And let's say that the `$id` variable will be the integer `42`.

The expected response would look like this:
```json
{
  "data": {
    "user": {
      "id": 123,
      "email": "foo@bar.com"
    }
  }
}
```

Here are some examples of how to execute this query in different languages - I've left out the authorization header for simplicity:

`curl`
```bash
curl -X POST 'https://example.com/graphql' \
-H 'Content-Type: application/json' \
-d '{"query":"query User(id: Int!) { user(id: $id) {id email} }", "variables": {"id": 42}}'
```

`python`
```python
# Every project will have a dependency like this if it's making HTTP requests
import requests
import json

data = {
  'query': 'query User(id: Int!) { user(id: $id) {id email} }',
  'variables': { 'id': 42 }
}

headers = { 'Content-Type': 'application/json' }

body = requests.post(
  'https://example.com/graphql',
  data=json.dumps(data),
  headers=headers
).json()
```

`Node`/`JavaScript`
```javascript
// Every project will have a dependency like this if it's making HTTP requests
import fetch from 'isomorphic-fetch'

const res = await fetch('https://example.com/graphql', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: '{"query":"query User(id: Int!) { user(id: $id) {id email} }", "variables": {"id": 42}}'
})

const body = await res.json()
```

`Ruby`
```ruby
require 'uri'
require 'net/http'
require 'json'

uri = URI('http://localhost:3000/graphql')
res = Net::HTTP.post_form(uri, 'query' => 'query {currentUser{id email}}', 'variables' => { 'id' => 42 }.to_json)
body = res.body
```

`PHP`
```php
$url = 'http://localhost:3000/graphql';
$data = array('query' => 'query {currentUser{id email}}', 'variables' => array('id' => 42));

$options = array(
  'http' => array(
    'header' => "Content-Type: application/json",
    'method' => 'POST',
    'content' => json_encode($data)
  )
);

$context = stream_context_create($options);
$result = file_get_contents($url, FALSE, $context);
```

### Summary

So there you have it! In my opinion, there's nothing mystical or particularly challenging to using GraphQL APIs - they're easy, efficient, and pretty fun/awesome. Admittedly, I kept the examples rather simple, and there are far more complex things that can be done with GraphQL (for example, trying to upload binary files can be a bit tricky), but for many APIs this is more or less all you need to know. So don't be afraid when you hear that an API is GraphQL - it's only some basic REST-like calls under the covers. Happy coding!

[restful]: https://en.wikipedia.org/wiki/Representational_state_transfer
[recent-study]: https://nordicapis.com/breaking-down-smartbears-2020-state-of-api-report/
[another-study]: https://2019.stateofjs.com/data-layer/graphql/
[this-article]: https://www.howtographql.com/basics/0-introduction/
[online-demo]: https://lucasconstantino.github.io/graphiql-online/
[types]: https://graphql.org/learn/schema/
[scalars]: https://graphql.org/learn/schema/#scalar-types
[fields]: https://graphql.org/learn/schema/#object-types-and-fields
[arguments]: https://graphql.org/learn/schema/#arguments
[spec]: https://spec.graphql.org/
[clients]: https://graphql.org/code/
[json]: https://www.w3schools.com/js/js_json_objects.asp
[params-as-get]: https://graphql.org/learn/serving-over-http/#get-request