Types

Introduction to the automatically generated GraphQL API.

Tensei automatically generates a fully featured and customisable GraphQL API for all your defined resources. This API would have queries, mutations and subscriptions for each resource.

Types

For each resource, a number of types are generated. Let's take an example Comment resource:

const { resource, text, textarea } = require('@tensei/core')

resource('Comment')
    .fields([
        text('Title').sortable(),
        textarea('Content')
    ])

The following types will be generated for the Comment resource:

type comment {
  id: ID!
  title: String
  content: String
  created_at: String
  updated_at: String
}

input comment_where_query {
  _and: [comment_where_query]
  _or: [comment_where_query]
  _not: comment_where_query
  id: id_where_query
  title: string_where_query
  content: string_where_query
  created_at: string_where_query
  updated_at: string_where_query
}

input insert_comment_input {
  title: String!
  content: String!
}

input update_comment_input {
  title: String!
  content: String!
}

input string_where_query {
  _eq: String
  _ne: String
  _in: [String!]
  _nin: [String!]
  _gt: String
  _gte: String
  _lt: String
  _lte: String
  _like: String
  _re: String
  _ilike: String
  _overlap: String
  _contains: String
  _contained: String
}

input comment_query_order {
  id: query_order
  title: query_order
}

enum query_order {
  asc
  asc_nulls_last
  asc_nulls_first
  desc
  desc_nulls_last
  desc_nulls_first
}
  • The type comment_where_query defines the where parameters accepted when fetching multiple comments.
  • The input insert_comment_input defines the accepted fields when inserting a comment.
  • The input update_comment_input defines the accepted fields when updating a comment.

Queries

For each resource, three queries are generated, one to fetch and filter all the resource records, one to count the resource records, and another to find a single resource record. Let's take an example Comment resource:

const { resource, text, textarea } = require('@tensei/core')

resource('Comment')
    .fields([
        text('Title').sortable(),
        textarea('Content')
    ])

This would generate the following queries:

type Query {
  comment(id: ID!): comment
  comments__count(where: comment_where_query): Int!
  comments(offset: Int, limit: Int, where: comment_where_query, order_by: comment_query_order): [comment]
}
  • comment to fetch a single comment by ID.
  • comments__count to count comments.
  • comments to fetch, filter and order all comments.

Hiding queries

Sometimes, you may not want a resource to be exposed via the API. You may use the .hideOnFetchApi() method on a resource to hide all of the queries for that resource:

resource('Comment')
  .hideOnFetchApi()

If you want to completely hide a resource from being exposed to the API, you may use the .hideOnApi() method.

resource('Comment')
  .hideOnApi()

Mutations

For each resource, six mutations are generated, one to insert, one to update, and another to delete a single resource record. Let's take an example Comment resource. The following mutations will be generated by default:

type Mutation {
  insert_comment(object: insert_comment_input): comment!
  insert_comments(objects: [insert_comment_input]!): [comment]!

  update_comment(id: ID!, object: update_comment_input!): comment!
  update_comments(where: comment_where_query!, object: [update_comment_input]!): comment!

  delete_comment(id: ID!): comment
  delete_comments(where: comment_where_query): [comment]!
}
  • insert_comment inserts a single comment.
  • insert_comments inserts multiple comments at a time.
  • update_comment updates a single comment by ID.
  • update_comments updates multiple comments that match a query.
  • delete_comment deletes a single comment by ID.
  • delete_comments deletes multiple comments that match a query.

Hiding mutations

If you do not want to expose inserting a specific resource via the API, you may use the .hideOnInsertApi() on the resource to automatically hide the insert_resource and insert_resources mutations from the GraphQL APi.

resource('Comment')
  .hideOnInsertApi()

You may also want to hide a specific field from the insert_resource field. You may do this using the .hideOnInsertApi() method on the field.

resource('Customer')
  .fields([
    text('Stripe Secret Key')
      .hideOnInsertApi()
  ])

Likewise, you may use the .hideOnUpdateApi() and .hideOnDeleteApi() to hide fields or resources from being exposed to the Graph QL API.

resource('Customer')
  .fields([
    text('Stripe Secret Key')
      .hideOnInsertApi()
  ])
  .hideOnUpdateApi()

If you want to completely hide a resource from being exposed to the API, you may use the .hideOnApi() method.

resource('Password Reset')
  .fields([
    text('Secret Token')
  ])
  .hideOnApi()

Subscriptions

For each resource, three subscriptions are generated: resource_inserted, resource_updated and resource_deleted. Consider we have a Post resource:

type Subscription {
  post_inserted(filter: JSONObject): post!
  post_updated(filter: JSONObject): post!
  post_deleted(filter: JSONObject): post!
}

Showing subscriptions

By default, subscriptions are not generated for a resource. To generate the resource_inserted subscription, you may use the .showOnInsertSubscription() method on the resource:

resource('Post')
  .showOnInsertSubscription()

You may also use the .showOnUpdateSubscription() and .showOnDeleteSubscription() to expose the resource_updated and resource_deleted subscriptions respectively.