Contracts 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 GraphOS trial. To compare GraphOS feature support across all plan types, see the pricing page.

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

Each contract can include different fields and types from each subgraph.

Benefits of contracts

Contracts offer these benefits:

  • Selective data access: Supergraphs 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. Contract-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 variant:

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

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

In the above example, a contract excludes types and fields marked with the internal @tag. The resulting contract schema defines a tailored GraphQL 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 graph router that uses a contract schema. Clients that use a contract router's endpoint can only execute GraphQL operations that the contract schema supports:

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 routers 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 selection set.

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

Contract documentation

In GraphOS Studio, 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 Apollo Federation 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 scalar types (default scalar types can never be excluded in Federation 1)

  • Enum types or their values

  • Input types or their fields

  • Arguments 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 contracts, 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:

Click to expand
  1. Identify the source variant you want to move to Federation 2.
  2. Save the details for each of that source variant's existing contract variants, most importantly each variant's associated filters.
  3. Delete all the source variant's existing contract variants.
  4. Now that the source variant has no associated contracts, you can configure it to use Federation 2 composition. Learn how.
  5. Recreate your deleted contract variants, which will now use Federation 2 composition like the modified source variant.
💡 tip
Feedback

Forums