7. Schema changes in the registry
3m

🙌🏽 Checking out the registry

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

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

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

We'll name our query getTrackAndModuleDurations and add the track field through the sidebar. We can see here that the length field 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 field to our query, 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 field. For this track, we'll also query for its list of modules, and the length and durationInSeconds fields. We can see the length field for a module has also been deprecated.

query getTrackAndModuleDurations($trackId: ID!) {
  track(id: $trackId) {
    length
    durationInSeconds
    modules {
      length
      durationInSeconds
    }
  }
}

Before running the query, let's make sure to give the trackId variable our favourite value c_0.

In the Variables panel:

{
  "trackId": "c_0"
}

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

Screenshot of the successful response 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 field, 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 fields. For each field, we can see the number of times it's been requested in the time period we set it to.

Screenshot of the field usage for the schema in Apollo

Notice how the deprecation for the length field is showing up on this page? We want to make sure that usage for this field 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!

Everything should be working the same as before, from the trainee catstronaut's perspective, but behind the scenes, we're using the new field.

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 the box to the blanks above

@deprecated directive
rename the old field
monitor usage of the new field
remove the old field
add the new replacement field
monitor usage of the old field
@replacement directive
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.

Previous
Next