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.

GraphQL ApiDoc template link

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 link

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

• The top-level query type, which defines the entry point of any GraphQL query to your Bookinfo services, specifies the productsForHome field. This field references the Product object type. For more information, see the GraphQL documentation on query types.
• Product, Review, ReviewerRating, and Rating are object types, which represent objects you can fetch from the Bookinfo services, and the fields each object has. For more information, see the GraphQL documentation on object types.

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 link

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

Next steps link

Now that your API schema fields are defined, choose how to execute requests that match this schema.

• Proxy requests to existing GraphQL backends: Incorporate your existing GraphQL backends into your Gloo setup to leverage Gloo features. GraphQL requests are proxied to these existing GraphQL backends, while leveraging the security and resilience features of the proxy. These APIs can exist within your Gloo setup as services, or if they are external to your cluster, can be represented in your Gloo setup as an external service.
• Define resolvers: Use GraphQL services that are deployed locally to the clusters in your Gloo environment to resolve schema fields. This process involves mapping each GraphQL resolved field in your schema definition to resolver configuration.