5. Contracts


In this section, we'll cover:

  • how to leverage Contracts to securely extend a subset of the to additional parties


  • Our running in the cloud


Now that we have a working built for KBT Threads, there is a desire to extend a subset of this functionality to additional external groups.

While this sounds straightforward, there are data privacy and security concerns that need to be addressed. We need to ensure that we are only sharing the proper information with these third parties. To do that, we will leverage contracts from Apollo to restrict access to sensitive information in our .

Contracts diagram

provide a way for us to segment access to our so that we only expose the data to the teams that need it. It does this by creating a separate with a subset of our original schema. In this way, we provide physical separation between our clients and their endpoints.

To get started in creating a , we need to tag in our schema.

The schema for our Customers has already been tagged. Go to the Schema page in to view our Customer :


Explorer showing tags in Schema

  1. Go to Settings on the left side of the page > This Variant (Current) > Contracts
  2. Click Create Contract. From there you will see the following dialog:

Explorer showing tags in Schema

  1. In the dialog, set the Contract Variant Name to public.

This is the first step toward creating our new . It will be named public and we will use as a baseline the current we created earlier. Once this is done, click Continue.

  1. Now that we have named our , it is time to leverage the tags we saw earlier to create our schema.

Here we can decide which tags we want to leverage, and if those tags should be included or excluded. In our case, we want to exclude the private tags for our public .

Select private as an excluded tag and click Generate Preview.


Explorer showing tags in Schema

now shows that this new schema will have five less . Let's click Review and take a look at the diff file. At this stage, we can see that the five tagged and the ones removed from the schema.


Explorer showing tags in Schema

Now that we can see this is the we want, lets click Create. This will create the contact . At this point, you can close out that window once the creation is successful or view the Lunch details, which will show the whole creation process details.

Now let's go to the contact - at the top of the page - and prep for deploying the GraphOS Router for this endpoint. On the top of the page, click where it shows your name, something in the form of <graph_name>@current, and select the , something like <graph_name>@public. Once there, select the Readme tab.


Explorer showing the newly created Contract

Copy your , as seen in the example above. We will now use that to deploy the to the cloud.


Explorer showing the newly created Contract

Deploy the Contract Router

Now that we have the , let's update it in our environment to prepare to deploy the . Go to the root directory of your workshop repository.

  1. Open up the .env file and change the to the new version for your (from @current to @variant).

  2. Now we need to edit the contract.yaml file to reflect the proper project id. Go to ./router/. From here, we need to modify contract.yaml to reflect the proper project name and unique service name. We need to find and replace two values in the .yaml file. We will replace two values.

Default ValueNew Value
federation-workshop<your-workshop-name> (This will be provided by Apollo)

There are many ways to find and replace text in this file, one command-line option is sed. Here are the commands to modify the file using sed in Unix.

sed -i '' 's/federation-workshop/<workshop-name>/g' contract.yaml
sed -i '' 's/contract-api/<yourname>-contract/g' contract.yaml
  1. With the proper in place, it's time to deploy the . To deploy the Router, go to the root folder of your workshop and run
In the root folder:
make deploy-contract
  1. Once that command is finished, we once again need to get the URL for this endpoint we have just deployed. To do that run the following command:
gcloud run services describe <yourname>-contract --region us-east1 --format 'value(status.url)'
  1. We need to paste this domain into so Explorer can this . In GraphOS Studio at the Readme page, your should say, This graph doesn't have an endpoint yet - add one in Connection Settings Click on Connection Settings. In here, past the domain that you received from the previous command.

Studio Contract Connection Settings

Then click Save. Once you have saved your URL, you are ready to test out this in Explorer. Go to the Explorer tab and let's build a :


Studio Contract Connection Settings

Hint: use the builder to easily build a simple query for a User's active cart

  1. In addition, we need to add a userId within the panel. Set the id to 10.
"userId": "10"
  1. Execute the by pressing Run button and check the result:
"data": {
"user": {
"activeCart": {
"subtotal": 178.99
Check List

Now, what if we want to access this user's PII data? We know that our underlying can serve up name, address, email, and phone number. Even though those do not show up in Explorer, let's try to access them. Manually type in firstName to the above, as shown below:

query ActiveCart($userId: ID!) {
user(id: $userId) {
activeCart {

We immediately see that the is indicating an error. Hovering our mouseover firstName tells us that we cannot firstName:


Explorer showing an invalid field due to Contract

What happens if we try to run it anyways?

You should receive an error message. This verifies that the we created cannot access those redacted , making it safe to share with third parties.

🎉 Congratulations! Your Contract is now ready to securely share data with third parties! 🎉

Up next

Now that we have used our both with our and the front-end, it's now time to explore some of the metrics that we can get in . Therefore, in the next section, we'll see how to we can use observability and metrics to understand, shape and grow our supergraph.