Skip to main content


For our first example, we are going to compose a GraphQL schema from the REST APIs at, a free online REST API with some fake data. We will use the API at /users to get a list of users, and /users/:id/posts to get the posts for each user, and compose them into a single GraphQL schema.

We can use the following formats to define our GraphQL schema: .graphql, .yml, .json.

Create one of the following files and paste the contents into it.

# Specify server configuration: Start tailcall server at
@server(port: 8000)

# Specify a base url for all http requests
@upstream(baseURL: "") {

query: Query

type Query {
# Specify the http path for the users query
users: [User] @http(path: "/users")

# Create a user type with the fields returned by the users api

type User {
id: Int!
name: String!
username: String!
email: String!

# Extend the user type with the posts field
# Use the current user's id to construct the path
posts: [Post] @http(path: "/users/{{}}/posts")

# Create a post type with the fields returned by the posts api
type Post {
id: Int!
title: String!
body: String!

The above file is a standard .graphQL file, with some minor additions such as @upstream and @http directives. Basically we specify the GraphQL schema and how to resolve that GraphQL schema in the same file, without having to write any code!