GraphcoolDocs
FAQ

Schema Mapping

Last updated a day ago Edit this page

The primary use case for the API gateway is to expose a custom API.

Table of Contents

Every Graphcool service comes with an auto-generated CRUD API for your data model. The API gateway can be used to customize the API that's exposed to your client applications. This customization can be implemented using the schema stitching API from graphql-tools.

#Example

Consider the following data model that's defined for a Graphcool service:

1
2
3
4
5
6
7
8
9
10
11
12
type User @model {
  id: ID! @isUnique
  name: String!
  alias: String! @isUnique
  posts: [Post!]! @relation(name: "UserPosts")
}

type Post @model {
  id: ID! @isUnique
  title: String!
  author: User! @relation(name: "UserPosts")
}

When deploying the service, Graphcool will generate the following CRUD API for you:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
type Query {
  # Read operations for `Post`
  Post(id: ID): Post
  allPosts(filter: PostFilter, orderBy: PostOrderBy, skip: Int, after: String, before: String, first: Int, last: Int): [Post!]!

  # Read operations for `User`
  User(alias: String, id: ID): User
  allUsers(filter: UserFilter, orderBy: UserOrderBy, skip: Int, after: String, before: String, first: Int, last: Int): [User!]!
}

type Mutation {
  # Create, update, delete operations for `Post`
  createPost(title: String!, authorId: ID, author: PostauthorUser): Post
  updatePost(id: ID!, title: String, authorId: ID, author: PostauthorUser): Post
  deletePost(id: ID!): Post

  # Create, update, delete operations for `User`
  createUser(alias: String!, name: String!, postsIds: [ID!], posts: [UserpostsPost!]): User
  updateUser(alias: String, id: ID!, name: String, postsIds: [ID!], posts: [UserpostsPost!]): User
  deleteUser(id: ID!): User

  # Set relation between `Post` and `User` node
  addToUserPosts(postsPostId: ID!, authorUserId: ID!): AddToUserPostsPayload
}

Now assume you actually want to the expose the following operations in your service:

1
2
3
4
5
6
7
8
type Query {
  viewer: Viewer!
}

type Viewer {
  me: User
  topPosts(limit: Int): [Post!]!
}

You can now use the utilities from graphql-tools to implement the mapping in 4 major steps:

  1. Create local version of the CRUD API using makeRemoteExecutableSchema.
  2. Define schema for the new API (the one exposed by the API gateway).
  3. Merge remote schema with new schema using mergeSchemas.
  4. Limit exposed operations from merged schemas (hiding all root fields except viewer) using transformSchema.

Check the actual example to learn how this works in practice.

Was this page helpful?