5. Contracts
10m

Overview

In this section, we'll cover:

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

Prerequisites

  • Our running in the cloud

Contracts

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 graph.

Contracts diagram

Contracts provide a way for us to segment access to our graph 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 . In this way, we provide physical separation between our clients and their endpoints.

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

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

https://studio.apollographql.com

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:
https://studio.apollographql.com

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 contract. 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 contract .

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.

https://studio.apollographql.com

Explorer showing tags in Schema

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

https://studio.apollographql.com

Explorer showing tags in Schema

Now that we can see this is the contract 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 graph name, something in the form of <graph_name>@current, and select the contract, something like <graph_name>@public. Once there, select the Readme tab.

https://studio.apollographql.com

Explorer showing the newly created Contract

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

https://studio.apollographql.com

Explorer showing the newly created Contract

Deploy the Contract Router

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

  1. Open up the .env file and change the graph ref to the new version for your contract (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 contract.yaml file. We will replace two values.

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

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.

router/
sed -i '' 's/federation-workshop/<workshop-name>/g' contract.yaml
sed -i '' 's/contract-api/<yourname>-contract/g' contract.yaml
  1. With the proper s 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 Studio so can query this contract . In GraphOS Studio at the Readme page, your graph 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.
https://studio.apollographql.com

Studio Contract Connection Settings

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

https://studio.apollographql.com

Studio Contract Connection Settings

Hint: use the Query 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 query 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 s can serve up name, address, email, and phone number. Even though those s do not show up in , let's try to access them. Manually type in firstName to the query above, as shown below:

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

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

https://studio.apollographql.com

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 contract we created cannot access those redacted s, 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 contract and the front-end, it's now time to explore some of the metrics that we can get in Studio. Therefore, in the next section, we'll see how to we can use observability and metrics to understand, shape and grow our supergraph.

Previous