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.

apiVersion: apimanagement.gloo.solo.io/v2
kind: ApiDoc
metadata:
  name: 
  namespace: 
spec:
  graphql:
    schemaDefinition: |-
      <schema>

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.

apiVersion: apimanagement.gloo.solo.io/v2
kind: ApiDoc
metadata:
  name: bookinfo-rest-apidoc
  namespace: bookinfo
spec:
  graphql:
    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
        }

Reference

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

Next steps

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