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.
- 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 theProduct
object type. For more information, see the GraphQL documentation on query types. Product
,Review
,ReviewerRating
, andRating
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
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.