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"
}
]
}
}
}
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 with this guide by checking out our starter project repo. Our starters let you instantly deploy a pre-configured project.
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 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($size: Int, $from: Int) {
getBookList(size: $size, from: $from) {
total
items {
title
}
}
}
{
"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($terms: String) {
getPostList(terms: $terms) {
items {
title
}
total
}
}
{
"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 jobs($where: TSWhereJobInput!) {
getJobList(where: $where) {
items {
title
company {
name
}
}
}
}
{
"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($sort: TSSearchSort) {
getPostList(sort: $sort) {
items {
_id
title
}
total
}
}
{
"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.
mutation($newTag: CreateTagInput!) {
createTag(input: $newTag) {
result {
_id
name
}
}
}
{
"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.