Define API schema

Start by defining your schema in an ApiDoc Gloo custom resource (CR). A schema definition determines what kind of data can be returned to a client that makes a GraphQL query to your endpoint.

You can use an ApiDoc CR to represent the GraphQL API schema specification language.

Looking to use gRPC resolvers for your GraphQL setup? See the gRPC resolver guide instead to define an ApiDoc CR in the gRPC API schema specification language.

GraphQL ApiDoc template

Provide a schema definition in GraphQL SDL format. Root-level query and mutation types are supported, and you must define at least a query type. For more information about the different schema features, see the GraphQL documentation.

kind: ApiDoc
    schemaDefinition: |-

Example GraphQL ApiDoc

In this example for the Bookinfo sample app, a query type and object types are defined.

In other words, when a client queries the productsForHome field, information about the id, title, descriptionHtml, reviews, and ratings fields from the Product object type are returned. The reviews and ratings fields reference object types of their own, which contain additional fields.

kind: ApiDoc
  name: bookinfo-rest-apidoc
  namespace: bookinfo
    schemaDefinition: |-
      type Query {
          productsForHome: [Product]
        """Each book has a product entry"""
        type Product {
          """Unique identifier for books"""
          id: String
          """The book title"""
          title: String
          """Description of a book in HTML"""
          descriptionHtml: String
          """List of reader reviews for this book. Queries the reviews REST service"""
          reviews: [Review] 
          """List of reader ratings for this book. Queries the ratings REST service"""
          ratings: [Rating] 
        """A book review"""
        type Review {
          """Name of the reviewer"""
          reviewer: String
          """Review details"""
          text: String
          """Reviewer Rating, this field is provided by the reviews REST service, which queries the ratings REST service"""
          rating: ReviewerRating
        type ReviewerRating {
          stars: Int
          color: String
        """A book rating"""
        type Rating {
          """Name of the user peforming the rating"""
          reviewer: String
          """Number of stars for this rating"""
          numStars: Int


For more information, see the Gloo Gateway API reference for the ApiDoc CR.

Gloo reports the status of Gloo custom resources in several places, such as in logs, when describing the object in kubectl, or when viewing the object in the Gloo UI. Unlike other Gloo custom resources, ApiDocs can be both an input and output object. For example, you can manually create an ApiDoc (input), or Gloo can automatically create an ApiDoc during discovery or translation processes (output). As such, status for ApiDocs is disabled. Because the status is disabled, you cannot review statuses for ApiDocs in kubectl. Also, you might notice ApiDocs reported as unhealthy in the Gloo UI even though the ApiDocs work. To verify that your ApiDocs are healthy, you can follow the steps in the ApiDoc guide.

Next steps

Now that your API schema fields are defined, you can choose resolver servers.