Docs
Launch GraphOS Studio

Creating and using contracts

Learn how to create, use, and edit contracts in GraphOS


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

NOTE

The steps below require an organization member with the Org Admin or Graph Admin role. Learn about member roles.

Create contracts

Prerequisites

Update your router and subgraphs

Before you create any :

  1. If you're using :

    • For Federation 2 , update your to version 2.0.0 or later of the @apollo/subgraph library.
    • For Federation 1 , update @apollo/subgraph to version 0.1.1 or later.

NOTE

@apollo/subgraph replaced @apollo/federation for instances acting as . Symbol names are unchanged.

  1. If you're using the @apollo/gateway library instead of the :

    • For Federation 2 , update your gateway's @apollo/gateway library to version 2.0.2 or later.
    • For Federation 1 , update your gateway's @apollo/gateway library to version 0.34.0 or later.

NOTE

Apollo recommends the over @apollo/gateway because it significantly improves performance and security. If you have a federated currently using @apollo/gateway, you can move to the without changing any other part of your . See the migration guide.

Older versions of the above libraries and tools don't fully support the required @tag .

(Fed1 only) Enable variant support for @tag

NOTE

This step is required for Federation 1 only. If you have a Federation 2 supergraph, proceed to the next step.

A uses one of your 's existing variants (called the source variant) to generate its schema. If your uses Federation 1, you need to enable its support for the @tag in GraphOS Studio:

  1. Open the Settings page for the you want to use as your , then select the This Variant tab:

    Edit supported directives in Studio
  2. In the Build Configuration section, click Edit Configuration and enable support for @tag.

1. Add @tags to subgraph schemas

With , you apply the @tag to types and in your to indicate whether to include or exclude them from your contract schema.

Before you can add @tags, you need to define the in your . The way you do this depends on which federation version you're using:

For example, let's take a look at this Federation 2 :

products.graphql
extend schema
@link(
url: "https://specs.apollo.dev/federation/v2.0"
import: ["@key", "@tag"]
)
type Query {
topProducts: [Product!]! @tag(name: "partner")
}
# All fields of the Product object type automatically inherit
# the "partner" tag so we can avoid tagging them individually
type Product @key(fields: "upc") @tag(name: "partner") {
upc: ID!
name: String!
description: String!
internalId: ID! @tag(name: "internal")
percentageMatch: Float! @tag(name: "experimental")
}

This schema applies the @tag to the following locations:

  • The Query.topProducts (which returns a list of Products)
  • The Product
  • Two of Product (internalId and percentageMatch)

Each @tag has a string name. You tag types and with the same name if they should be included or excluded as a group by a particular .

💡 TIP

For in-depth details on valid @tag usage, see Rules for @tags and contracts.

Whenever composes your 's supergraph schema, that schema retains all the @tags from your . removes some other by default. Learn more.

2. Publish updated subgraph schemas

After you've added tags, update your by publishing your updated subgraph schemas to .

💡 TIP

After publishing, if Studio doesn't reflect the @tags you've added in your , ensure you've updated all required libraries and tools. If you obtain your via , older subgraph libraries might strip the @tag .

3. Create a contract

  1. Open your 's Settings page and select the This Variant tab. Open Contracts in the left nav:

    Contract settings in Studio
  2. Click Create Contract to open the following dialog:

    Create contract dialog
  3. In the first step of the dialog, provide the following:

    • A name for your new
    • The to use

    NOTE

    You can't change these values after the is created.

  4. Click Continue.

  5. Specify tag-based filters for your :

    Create contract dialog
    • The dialog detects all tag names used in your 's schema and populates the Excluded Tags and Included Tags dropdown lists with those names. You can add any number of tag names to each list.

    • You can also add tag names not yet present in your 's schema. If you later add tags with that name, the honors them.

💡 TIP

In 2, if you want to exclude a type or from your 's API schema and all its schemas, you can use the @inaccessible instead of @tag. For details, see Using @inaccessible.

  1. When you're finished adding tag names, click Generate Preview. Studio attempts to generate a schema based on the filters you provided and displays the result. After you generate the preview, click Review to continue to the next step.

    Result of contract preview generation
  2. Review all the details of your :

    Create contract dialog
  3. If everything looks right, click Create. This kicks off the generation of your and its initial contract schema as a launch.

NOTE

might encounter an error while generating your schema. For descriptions of these errors, see Errors.

Using contract variants

You can use your to provide contract routers or contract documentation to your users. For example, you can complete the managed federation setup for a new instance that uses your .

Automatic updates

Apollo automatically updates your schema whenever any of the following occurs:

  • successfully composes an updated for the 's .
  • You edit your contract.

These automatic updates ensure that your schema reflects your 's latest version and that the correct types and are included and excluded.

Your managed contract routers automatically fetched updates to your schema.

Edit contracts

NOTE

You can't change an existing 's name or . Instead, you can create a new contract and delete the existing contract variant if you no longer need it.

After you create a , you can edit its lists of included and excluded tags:

  1. From the list in your 's Settings page, click Edit Contract where shown:

    Edit contract menu

    This opens a dialog similar to the one you used to create the contract. Make any required changes.

  2. If you change the 's included or excluded tags, automatically runs contract checks to determine whether those changes will affect any clients using your . The result of these checks appears in the Review Schema step of the edit dialog:

    Contract edit dialog with checks result
  3. The dialog shows Contract Updated once the update is complete.

Run contract checks

If you run schema checks in (which we recommend for all graphs), those checks include contract checks for any that acts as a for . Contract checks help your team identify when proposed changes to a source variant will negatively affect one or more downstream contracts.

NOTE

To run checks via rover subgraph check, you must update the Rover CLI to v0.8.2 or later.

  • If you use Rover v0.8.0 or v0.8.1, checks run, but ignores any contract check failures in blocking downstream variants you've set.
  • If you use a version prior to v0.8.0, rover subgraph check does not run checks at all.

When you run on a , checks execute alongside the other checks for that variant (composition checks and operation checks).

checks rely on the generated by , so they don't execute if composition checks fail.

checks do the following for each of a 's associated :

  1. Use the 's proposed (validated by checks) to generate and validate an updated schema.
  2. Run checks against the updated schema.

On your 's Checks page in Studio, checks appear as Downstream:

Downstream checks shown in Studio UI

You can click the Downstream item in the Tasks column to view a summary of all checks that ran and click a particular check to view more details:

Downstream checks shown in Studio UI

Failing contract checks

Unlike other types of checks, failing checks don't cause their associated workflow to fail by default. This means that the rover subgraph check command doesn't return an error state that would prevent a CI task from merging or deploying changes to the .

If you want failing checks to fail your entire checks workflow, you can set the blocking downstream variants configuration for your . If checks fail for any of these specified contract variants, the source variant's checks workflow does fail.

To set blocking downstream :

  1. Open your 's Checks page and select the This Variant tab.

  2. Click Configuration and scroll down to the Blocking Downstream Variants section:

    Blocking downstream variants for checks
  3. Select each that should be a blocking downstream variant.

From now on, whenever run for your , those checks fail if checks fail for any blocking downstream variant.

Previous
Overview
Next
Reference
Edit on GitHubEditForumsDiscord

© 2024 Apollo Graph Inc.

Privacy Policy

Company