7. Schema changes in the registry

🙌🏽 Checking out the registry

Our API changes have been deployed to production, so let's have a look at the Apollo schema registry.

The Changelog page

Go to your deployed in Apollo Studio, and click on the Changelog page in the left sidebar. This page shows every update made to our schema, presented in a "diff"-like format that may feel familiar: green pluses for additions, red minuses for deletions, and yellow circles for modifications from previous versions. Pretty handy to get a quick understanding of the schema evolution over time!

Screenshot of the changelog page in Apollo Studio, showing fields that have been added, removed and modified

We can see a new schema version published today with the commit hash, showing how many types and were added, removed, and modified. These were the exact changes we made earlier, now available for other members of our organization to see!

The items displayed in the Changelog are interactive. For example, when we click on the durationInSeconds we just added, we're sent to the Reference tab of the Schema page, where we get a breakdown of our schema's entry points, objects, , and more.

Screenshot of the Schema Reference page, highlighting the `durationInSeconds` field

Building a new test query

Let's use the Explorer to build a new so that we can try out our updated track and module specifically on our deployed production .

We'll name our GetTrackAndModuleDurations and add the track through the sidebar. We can see here that the length is now greyed out with a little warning icon that shows our deprecation message.

Screenshot of Explorer showing the deprecated length field

We can still add a deprecated to our , but the deprecation warning will always be there to remind us that we should use the new field instead.

Let's add the new durationInSeconds . For this track, we'll also for its list of modules, and the length and durationInSeconds . We can see the length for a module has also been deprecated.

query GetTrackAndModuleDurations($trackId: ID!) {
track(id: $trackId) {
modules {

Before running the , let's make sure to give the trackId our favourite value, c_0. Add the following to the Variables panel:

"trackId": "c_0"

After running the , we can see in the response that both are resolved successfully with the same value!

Screenshot of the successful response to the GetTrackAndModuleDurations query in Explorer
Which of these are true about a field that has been assigned the @deprecated directive?

Our schema is updated, but we're not quite done with our plan! Step 3 was to monitor usage for the old , before we can move on to step 4, removing the old field completely. We can use the registry to track API state and usage down to the field level.

📉 Field usage

Let's hop over to the Fields page and explore the current state of our schema, with all of its types and . For each field, we can see two metrics that have been measured for our in the last day: field executions and referencing .

The Fields page displaying field executions and referencing operations for each field

The number of field executions represents how many times the server has executed the function for a specific over the given period.

Referencing operations, on the other hand, lists the number of in a given period that have included the particular .

Note: By default, this period is set to the last day, but we can customize the range by toggling the filter at the top of the page.

Addressing deprecated fields

We can see from the metrics on the Fields page that our deprecated length is still being used.

Screenshot of the field usage for the `length` field in our schema

We want to make sure that usage for this goes down to zero. To do so, we'll need to make a few changes to our client app, replacing all the occurrences of length with durationInSeconds. Then we commit, push and deploy.

Note: We'll leave these changes to the client app as an exercise for you! Make sure to test your changes locally before deploying to production.

After those changes to the client are made, our API change will be fully rolled out on both server and client side!

From the trainee catstronaut's perspective, everything should be working the same as before. But behind the scenes, we're using the new .

Replacing a field
When replacing a field in your schema, there are a number of steps you should follow. First, 
 to your schema. Next, 
 by using the 
. Then, make sure to 
, waiting until usage of that field goes down before we can 

Drag items from this box to the blanks above

  • monitor usage of the new field

  • remove the old field

  • @replacement directive

  • rename the old field

  • @deprecated directive

  • monitor usage of the old field

  • add the new replacement field

  • deprecate the old field

Kudos for making our API a little better 🎉! We now have a good understanding of the steps to modify and improve it over time. In the final lesson, we'll explore how to keep our fingers on the pulse of our API and where we can take it from there.


Share your questions and comments about this lesson

Your feedback helps us improve! If you're stuck or confused, let us know and we'll help you out. All comments are public and must follow the Apollo Code of Conduct. Note that comments that have been resolved or addressed may be removed.

You'll need a GitHub account to post below. Don't have one? Post in our Odyssey forum instead.