APIs

What are APIs

APIs stand for Application Programmable Interfaces. This is how two or more items, people, places or things are able to communicate to each other. On the simplest level, a student raising a hand in class to ask a question is an API. They are invoking the agreed method for signaling to the other they would like to speak.

APIs for servers are similar, the server has a defined way that it likes to be asked for things like looking for content, updating content, creating content or deleting content.

How to use our APIs

Every GraphCMS project comes with at least two APIs - the default Content API and the the Management API. The content API handles all the information about the content you've saved in a project. The management API handles how your project is structured, who has access and more.

Public API Permissions

For more information about APIs, see our reference on API basics.

Permanent Auth Tokens

Permanent Auth Tokens allow you provide secured access to your API through a Authorization token.


Working with APIs

Your API endpoint is located in the API Settings. The endpoints are divided by environments. You can use the drop-down icon next to the URL to locate additional Environment endpoints. The default included with every GraphCMS project is called "master".

Locating API Settings

  1. Navigate to the settings tab in the bottom group of icons in the left-hand sidebar.
  2. In the collapsable sidebar, navigate to the tab labeled "API Access"

API Settings are split between Public API settings and Permanent Auth Tokens. Each of these sections are broken down by their behavior for both Queries and Mutations.

Public API Settings

By default, your API is secured and only available to internal tooling (the API Playground). Your API settings can be configured as a matrix across:

  • Access to specified content stages (PUBLISHED and / or DRAFT)
  • Access to queries (read), or mutations (create, update, delete)

Your API specifies a default stage for delivering content. You can change this behavior by toggling which stage to deliver from by default in the bottom of the "Query" settings of your Public API Settings.

Exposing / Hiding Content Stages

You can expose / Hide a content stage by checking / unchecking the box next to the Stage you want available from your API. You can enable mutations from an endpoint as well by checking the box next to "mutations."

To enable mutations, you need to allow queries from DRAFT as well as the returned subfields from a mutation are not restricted by stage.

API Settings with Auth Tokens

Create an Auth Token

  1. Provide a name then configure the API settings as you would in the Public API Settings.
  2. Press Create.
  3. At the bottom of your API Settings page you can press "copy" next to an Auth token to copy the token.

Edit an Auth Token

  1. Locate the Auth Token you want to work with at the bottom of your API Settings page.
  2. Press edit.

Delete an Auth Token

  1. Locate the Auth Token you want to work with at the bottom of your API Settings page.
  2. Press delete.

Tools for Testing your API

For a large list of tools for working with GraphQL, see this "Awesome GraphQL list".


Were you expecting something more?

We are constantly contributing to our documentation, but if you spot something we're missing, let us know and we'll be sure to add it.

This site uses cookies to provide you with a better user experience. For more information, refer to our Privacy Policy