Docs
Launch GraphOS Studio

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 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. declaratively grant access to specific subsets of the supergraph, so graph consumers only access relevant data.

  • Data security and privacy: 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: 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 filters specific portions of your 's schema into a different GraphOS variant:

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

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

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 excludes types and marked with the internal @tag. The resulting schema defines a tailored API for external audiences.

How to use contracts

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

Contract routers

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

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

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

can safely connect to the same 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 can still be used in a @requires selection set.

NOTE

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

Contract documentation

In , each 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 while omitting irrelevant types and .

Federation 1 limitations

behave slightly differently depending on which version of your uses—either Federation 1 or Federation 2. Most importantly, graphs that use Federation 1 cannot use @tags to exclude the following from a 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 or interface fields

Contracts and Federation 2

To create a that uses Federation 2, the contract's 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 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 with the following steps:

💡 TIP

Previous
Launches
Next
Creating and using contracts
Edit on GitHubEditForumsDiscord

© 2024 Apollo Graph Inc.

Privacy Policy

Company