Call the GraphQL API

A project's GraphQL API is available it's endpoint: api.takeshape.io/project/[project-id]/graphql

You can find your project's ID in its URL. When inside your project, the ID follows after https://app.takeshape.io/project/.

You can find and copy your project's API endpoint from the left sidebar within the API section.

Your request should include the API key you created as a Bearer Token.

For a simple request using fetch set the body of the request as a stringified object with the query key containing the GraphQL query.

const query = `
{
    getBookList {
        items {
            title
        }
    }
}
`;

fetch(`https://api.takeshape.io/project/${PROJECT_ID}/graphql`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${API_KEY}`
  },
  body: JSON.stringify({ query })
})
  .then((res) => {
    return res.json();
  })
  .then((json) => {
    console.log(json);
  });

The response will look like this:

{
  "data": {
    "getBookList": {
      "items": [
        {
          "title": "Peter Pan"
        },
        {
          "title": "The Lion, the Witch, and the Wardrobe"
        },
        {
          "title": "Treasure Island"
        },
        {
          "title": "Alice in Wonderland"
        }
      ]
    }
  }
}

danger

When you're making GraphQL requests from client-side code, you're exposing your API key to the world. Make sure you only use read-only permissions on keys you intend to use in queries from the browser.

Queries

Queries are automatically created for a shape with built-in data storage.

Here's an example of a query for books and for authors, from a project using our Shape Books pattern.

Follow Along

Follow along with this guide by checking out our starter project repo. Our starters let you instantly deploy a pre-configured project.

Query
query {
  books: getBookList {
    items {
      title
      author {
        name
      }
    }
  }
  authors: getAuthorList {
    items {
      name
      authored {
        items {
          title
        }
      }
    }
  }
}

As you can see, with GraphQL we're able to get data about books and authors at the same time. Additionally, for each book we get a little information about its author, and for each author we get a little information about the books they've written.

Pagination

Auto-generated queries support pagination with the from and size arguments and total return value.

from - The offset to start from.
size - The maximum number of items to return. size is limited to 250.
total - The total number of items matching your search criteria.

With these three values, you can generate and navigate pages of your responses.

Query
query ($size: Int, $from: Int) {
  getBookList(size: $size, from: $from) {
    total
    items {
      title
    }
  }
}

Variables
{
  "size": 12,
  "from": 0
}

Filtering

Generated queries also support two approaches to filtering using the terms and where arguments.

`terms`

The terms argument will filter results that match the provided string in any of their text fields.

Query
query ($terms: String) {
  getPostList(terms: $terms) {
    items {
      title
    }
    total
  }
}

Variables
{
  "terms": "Lewis"
}

`where`

The where argument allows for more complex filters that can also be combined using the boolean operators AND, OR, and NOT.

Query
query jobs($where: TSWhereJobInput!) {
  getJobList(where: $where) {
    items {
      title
      company {
        name
      }
    }
  }
}

Variables
{
  "where": {
    "OR": {
      "title": {
        "match": "front end"
      },
      "title": {
        "match": "back end"
      }
    }
  }
}

Sorting

Use the sort argument to order the results of generated queries. It takes the name of a field to sort by and an order, either asc for ascending ordering or desc for descending ordering.

Query
query ($sort: TSSearchSort) {
  getPostList(sort: $sort) {
    items {
      _id
      title
    }
    total
  }
}

Variables
{
  "sort": {
    "field": "_updatedAt",
    "order": "desc"
  }
}

Mutations

Mutations for creating, duplicating, updating, and deleting records are generated for shapes that use built-in data storage.

Mutations must use the mutation keyword at the beginning of their query and data as an input argument. When duplicating, updating or deleting a record, the input should contain the _id for the record you'd like to operate on. When creating a new record, you don't need to provide a unique id—one will be generated for you.

These built-in mutations will resolve with the created, duplicated, or updated record, allowing you to query their data as result of a successful mutation. When deleting records, the result will be a boolean indicating success.

Query
mutation ($newTag: CreateTagInput!) {
  createTag(input: $newTag) {
    result {
      _id
      name
    }
  }
}

Variables
{
  "newTag": {
    "name": "My New Tag"
  }
}

Cache Control

GraphQL and Rest resolvers support a TTL caching option. Caching can be disabled by including a header in your request.

X-TakeShape-Cache: 'false'

Rate Limits and 429 Errors

If you receive a 429 error you are bumping into a rate limit. 429 means "Too Many Requests". You can use the following HTTP response headers to tune requests to the API.

X-RateLimit-Limit: NNN
X-RateLimit-Remaining: NNN
X-RateLimit-Reset: NNN

X-RateLimit-Limit - How many API requests you can make per second. Your limit is measured over a 60 second window.

X-RateLimit-Remaining - How many API requests are remaining in the window.

X-RateLimit-Reset - When the rate limit window resets.

Queries​

Pagination​

Filtering​

terms​

where​

Sorting​

Mutations​

Cache Control​

Rate Limits and 429 Errors​