Skip to main content

Call the GraphQL API

You can make requests to the TakeShape GraphQL API from your project endpoint:

https://api.takeshape.io/project/[project-id]/v3/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}/v3/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#

When you create a shape with built-in data storage, TakeShape automatically creates queries for getting results.

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

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#

TakeShape's automatically-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 100.
  • 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#

Automatically-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 TakeShape's automatically 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#

TakeShape also automatically creates mutations for creating, duplicating, updating, and deleting records 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.