Skip to main content

GraphQL

By adding queries and mutations from multiple connected services, or by writing your own queries and mutations that use services, you can stitch together exactly the API you need to interact with all of the services your app or business depends upon.

Here's some GraphQL APIs you can easily add to your project:

In the following walkthrough, we'll be using the Rick and Morty GraphQL API.

Connect a GraphQL service#

Connecting a GraphQL service requires you to know the endpoint you're connecting to and any authentication requirements it has.

When you're ready, start by going to your project's Schema tab.

Then, click Connect Service in the top right corner of the services table. From here, select GraphQL as the service you'd like to connect.

Here, we're connecting with the Rick and Morty GraphQL API by providing a basic Name and Slug for our service, then defining the Endpoint for the API.

The Rick and Morty GraphQL API doesn't require any authentication, but many other GraphQL APIs do. Authentication for GraphQL APIs uses Bearer Token authentication by default. If you need to use a different header field for your access token, you can customize it using the "Auth Header" field.

When your service is fully and correctly configured, click Save.

Add queries or mutations#

In the web client#

After connecting your GraphQL service, you'll probably want to add some queries that make use of it.

The easiest way to add queries and mutations from a GraphQL service is from the web client. After making a connection, we'll prompt you to add queries and mutations that are available on that service's schema. This lets you proxy requests to 3rd parties in your own project's API.

After successfully connecting your GraphQL service, you'll be taken back to the Schema page.

A dialog will appear with a list of queries and mutations that we found in the connected service. You can select just the ones you want to add, see the args they accept, and the shape of the data they return.

When you've selected the queries and mutations you'd like to add to your schema, click Save.

You'll now see that queries and mutations from the Rick and Morty API are now available in this schema. Now in our API, we can query for paginated lists of characters, episodes, and locations.

Since these queries are providing data from a source external to TakeShape, notice that they use a different icon in their "Service".

By editing the Schema File#

You can also directly edit your project schema to add queries and mutations to GraphQL services. After editing your schema, you can then upload it to your project using the CLI or API.

Your API requests will need to be authenticated with an API Key as a Bearer Token. Learn more about making API requests and creating API keys.

Queries and mutations have the same structure, with the same required fields. They use separate keys in the schema file: queries and mutations, respectively.

To add a new query or mutation to your schema, you can provide a new entry to the "queries" or "mutations" objects with the following properties:

  • shape: string (required) Specifies which shape is returned by the query or mutation. The shape can refer to a shape in the schema's "shapes" object or a shape that's available on a service schema (we provide an example of a remote shape reference below).
  • resolver: object (required) Configures the resolver for your query or mutation. Learn more about resolvers
  • description: string (optional) Provides more detail about what the query or mutation is for. This will be displayed in the automatically-generated GraphQL API docs (optional)
  • args: string (optional) The args field specifies the name of a Shape for the input arguments required by your resolver. If your query does not need any input, you can omit this.

Example: TakeShape Query#

Here, we're creating a custom query for an existing shape, using the built in takeshape:list resolver:

"getPostById": {
"shape": "Post",
"resolver": {
"name": "takeshape:get",
"service": "takeshape:local",
"options": {
"model": "Post"
}
},
"description": "Get a Post by ID",
"args": "TSGetArgs<Post>"
}

Here, the shape of the query args is a built-in template provided by TakeShape. The generic  TSGetArgs template type generates the arguments expected by the takeshape:get resolver, using the Post shape as its input.

Example: Rick and Morty GraphQL API Query#

Here, we're using a connection to the Rick & Morty GraphQL API to define a query that fetches a list of all the characters in the show:

"getRickAndMortyCharacters": {
"shape": "Rick_Characters",
"description": "Get the list of all characters",
"resolver": {
"name": "graphql:query",
"service": "graphql:rick-and-morty",
"options": {
"fieldName": "characters"
}
}
"args": {
"type": "object",
"properties": {
"page": {
"type": "integer"
},
"filter": {
"$ref": "#/shapes/Rick_FilterCharacter/schema"
}
}
}
}

When defining the query, we set the resolver to use the generic graphql:query resolver, combined with the graphql:rick-and-morty service available in the schema. We define the query's args to provide pagination and filtering.

For the complete list of resolvers, see the Schema Spec