Quickstart
This guide should take you 10 minutes to complete.
It's easy to build a GraphQL API using TakeShape. Follow along with our quickstart guide to set up a project and call it from your application.
Create an account
Start by creating a free account. TakeShape is free up to 10k monthly API requests, so you can try out or even build a basic application risk-free. After you pass 10k monthly requests, you'll be charged based on your usage.
You don't need to provide a credit card to use TakeShape, but we adding one to production project will prevent service interruptions if the project exceeds the free limit. You can add a credit card in your project's billing settings.
Create a project
Next, we'll create a blank project. For our Source
, we'll select "Blank Project". Let's name our new project "Travel Blog".
After you create the project, you'll be taken to your project's dashboard. It offers quick access to the steps you'll need to finish setting up your project, which are the same as you'll find in this guide. We encourage you to stick with this guide for now, but know that the dashboard will always be there for you for future projects.
Connect a service
In the first step on the dashboard, select on the "Connect Service" link to add a new service. From the grid of available services, select the "GraphQL" provider. In the following form, fill in details for the public Countries GraphQL API:
- Name:
Countries
- Slug:
countries
- Namespace:
Countries
- Endpoint:
https://countries.trevorblades.com/
- Authentication:
None
Once the service is configured, save it. TakeShape will then examine the service you connected and suggest queries and mutations from that service to add to your API. Go ahead and select the Countries_country
query, which will return details of a specific country.
After selecting your query and selecting "Save", you'll see your schema now includes the query and all the remote shapes it depends upon:
Countries_Continent
Countries_Country
Countries_Language
Countries_State
These shapes are added since they're all returned by the Countries_country
query, and they all have the Countries
namespace since they belong to the service.
Explore your API
Now it's time to test your new API. Use the API tab to switch over to the API Explorer. Paste in this query and select the "Run" button:
query Japan {
Countries_country(code: "JP") {
name
emoji
currency
capital
}
}
In the response, you'll get back information about Japan, along with some analytics about your query's performance. Open up the bottom Debugger panel to see more detail about how your requests perform.
Query your API from the command line
Finally, it's time to call your API from your local machine.
Here's the command:
export TAKESHAPE_API_KEY="xxxx"
export TAKESHAPE_ENDPOINT="xxxx"
curl -g \
-X POST \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $TAKESHAPE_API_KEY" \
-d '{"query":"query Country($code: ID!) { Countries_country(code: $code) { name emoji currency capital } }"}' \
$TAKESHAPE_ENDPOINT
You'll see that there's two pieces of data you need
The first thing you'll want to do is create a .env
file in your project that includes the secrets TAKESHAPE_ENDPOINT
and TAKESHAPE_API_KEY
:
TAKESHAPE_ENDPOINT=xxxxx
TAKESHAPE_API_KEY=xxxxx
When you're in your project in the TakeShape web client, you can find your project's endpoint in the sidebar of the API tab.
You can create an API Key from within the API tab. Pick the dev
permission for your key, then save it. After saving, you'll be presented with a one-time secret string. Copy it into your .env
file.
Once you've got your secrets, install some libraries to help make your request:
npm i --save node-fetch dotenv
Now, querying TakeShape is as simple as making a network request:
require('dotenv').config();
const fetch = require('node-fetch');
async function query(query, variables) {
const res = await fetch(process.env.TAKESHAPE_ENDPOINT, {
headers: {
Authorization: `Bearer ${process.env.TAKESHAPE_API_KEY}`
},
method: 'POST',
body: JSON.stringify({query, variables})
});
return res.json();
}
const COUNTRY_QUERY = `
query Country($code: ID!) {
Countries_country(code: $code) {
name
emoji
currency
capital
}
}
`;
query(COUNTRY_QUERY, {code: 'JP'}).then(data => console.log(data));
Run this file with node takeshape.client.js
and you'll see it return your data.
{
"data": {
"Countries_country": {"name": "Japan", "emoji": "🇯🇵", "currency": "JPY", "capital": "Tokyo"}
}
}
Next steps
Keep reading
Continue reading the docs to become an expert at connecting services, querying your API, and unlocking the full power of your schema.
Join the community
Join TakeShape's community Slack group to meet other TakeShape users, share your projects, and get personal support from the TakeShape team.
Explore our starter projects
We've built a gallery of starter projects using different static site generators, application frameworks, and connected services to help kickstart your next Jamstack project. Check out their repos, reference the code, and use them as the starting point for building on your own.