Join us from October 8-10 in New York City to learn the latest tips, trends, and news about GraphQL Federation and API platform engineering.Join us for GraphQL Summit 2024 in NYC
Docs
Start for Free

Contract Overview

Deliver different subsets of your supergraph to different consumers


This feature is only available with a GraphOS Enterprise plan.
You can test it out by signing up for a free Enterprise trial.

A unified provides a single source of truth for your organization's data. That data likely has different consumers with different needs and permissions. contracts enable you to deliver different subsets of your supergraph to different consumers.

Filter schema
according to contract A
Filter schema
according to contract B
Complete
supergraph schema
Contract
schema B
Contract
schema A

Each can include different and types from each .

Benefits of contracts

offer these benefits:

  • Selective data access: often contain a wide range of data, including information that's irrelevant to specific audiences. Contracts declaratively grant access to specific subsets of the supergraph, so graph consumers only access relevant data.

  • Data security and privacy: Contracts bolster data security and privacy by enabling the exclusion of confidential data from certain consumers. This ensures that only authorized parties can access sensitive data.

  • Documentation and guidance: Contracts provide documentation to client developers. -specific documentation helps developers better understand and more easily interact with the data they are authorized to access.

How contracts work

Each contract filters specific portions of your supergraph's schema into a different GraphOS :

Contract variant
Contract variant
Source variant
Filter schema
according to contract A
Filter schema
according to contract B
Contract
schema A
Contract
schema B
Complete
supergraph schema

Contracts are created by adding @tag to your . @tags declare which types and fields to include or exclude from specific contract .

Source variant subgraph schema
type Product {
id: ID!
name: String!
codename: String! @tag(name: "internal")
}
Contract variant API schema
type Product {
id: ID!
name: String!
# codename field is filtered out of this contract variant
}

In the above example, a contract excludes types and fields marked with the internal @tag. The resulting contract schema defines a tailored API for external audiences.

How to use contracts

You usually create a contract to support a contract router, contract documentation, or both.

Contract routers

You can deploy a managed instance of your that uses a contract schema. Clients that use a contract router's endpoint can only execute GraphQL that the contract schema supports:

Standard router
Contract router
Supergraph
(all subgraphs)
Admin app
User app

This enables you to hide experimental types and fields still in development or limit a particular audience's access to only the portions of the graph they need.

Contract can safely connect to the same subgraph instances as any other router because their clients can only interact with data represented in the contract schema. This does not affect internal routing. For example, filtered fields can still be used in a @requires .

NOTE

Any @tag in a 's is also present in a contract variant's supergraph schema.

Contract documentation

In , each contract variant has its own README, schema reference, and Explorer. If you make a contract variant public, you can provide these resources to external client developers to help them interact with a specific portion of your graph while omitting irrelevant types and fields.

Federation 1 limitations

Contracts behave slightly differently depending on which version of your graph uses—either Federation 1 or Federation 2. Most importantly, graphs that use Federation 1 cannot use @tags to exclude the following from a contract schema:

  • Custom types (default scalar types can never be excluded in Federation 1)
  • Enum types or their values
  • Input types or their s
  • of object fields or interface fields

Contracts and Federation 2

To create a contract variant that uses Federation 2, the contract's source variant must also use Federation 2. Learn how to move an existing variant to Federation 2.

Moving an existing contract to Federation 2

If a Federation 1 source variant already has one or more associated , it isn't possible to move that variant or its contract variants to Federation 2. Instead, you need to delete and recreate your contract variants with the following steps:

💡 TIP

Previous
Launches
Next
Creating and Using Contracts
Rate articleRateEdit on GitHubEditForumsDiscord

© 2024 Apollo Graph Inc., d/b/a Apollo GraphQL.

Privacy Policy

Company