GraphQL for REST Devs

If you've worked with REST APIs before, GraphQL will feel a bit different. Here's a quick rundown of the key differences.

One endpoint, many queries

With REST, you use different URLs for different resources:

GET /posts
GET /channels
GET /organizations

With GraphQL, everything goes to one endpoint:

POST https://api.buffer.com

Instead of choosing a URL, you write a query that describes what you want. The endpoint is always the same.

You choose what comes back

With REST, the server decides what's in the response. You might get 30 fields back when you only need 2. With GraphQL, you pick exactly which fields you want:

query {
  channels(input: { organizationId: "your_org_id" }) {
    id
    name
  }
}

This returns only id and name, nothing extra.

Queries read, mutations write

REST uses HTTP verbs to indicate intent: GET to read, POST to create, PUT to update, DELETE to remove.

GraphQL uses operation types:

query - read data (like GET)
mutation - create or change data (like POST/PUT/DELETE)

Both are sent as POST requests to the same endpoint. The operation type inside the request body tells the server what you're doing.

# Reading data
query {
  account { id }
}

# Writing data
mutation {
  createPost(input: { text: "Hello!", channelId: "your_channel_id", schedulingType: automatic, mode: addToQueue }) {
    ... on PostActionSuccess { post { id } }
  }
}

Errors work differently

REST uses HTTP status codes: 404 for not found, 401 for unauthorized, 500 for server error.

GraphQL always returns HTTP 200. Errors are in the response body, in two places:

1. The errors array - for non-recoverable problems (bad auth, server error):

{
  "errors": [
    {
      "message": "Not authorized",
      "extensions": { "code": "UNAUTHORIZED" }
    }
  ]
}

2. Typed errors in the data for recoverable problems (validation, limits):

mutation {
  createPost(input: { ... }) {
    ... on PostActionSuccess { post { id } }
    ... on MutationError { message }
  }
}

Buffer uses typed union errors so you can handle specific error cases in your code. See Error Handling for details.

Tools for exploring

Buffer API Explorer: try queries right in your browser
API Reference: browse all available queries, mutations, and types
Any GraphQL client: tools like Postman or Insomnia work great too