Overview

Time to set up the playground with the data we'll explore throughout this course.

In this lesson, we will:

• Bring our REST API response into the Mapping Playground
• Explore mapping expressions using the $ symbol
• Learn how to reduce syntax with shorthand expression

What we're building

We use connectors to connect to REST API endpoints from our schema—so let's actually inspect the schema we'll write our mapping expressions for!

The schema

We'll build onto this schema throughout the remainder of the course, but here's what we're starting with: a single entrypoint, Query.products, returns a list of Product types. Each Product we return should specify things like its name, tagline, and whatever tags have been applied to it.

Let's get going!

Our REST API

Time for some data. To get started, expand the JSON collapsible below and copy its contents.

Lots of data in there. The response from the REST API is big; and it's only growing from here! We'll find a lot of fields we're interested in here, but many more that contain nested objects and other bits of data we might not need.

We can't get any more specific with the data we request from our REST API—but we CAN simplify the response considerably with connectors and a mapping expression.

Investigating with the playground

Copy all of the data on this page, and let's return to our Mapping Playground. Delete the existing contents in the Input panel, and let's paste in the JSON response from our REST API.

We've got errors—and rightly so! Our Mapping panel remained the same, and it's still referencing fields that can't be found on our new JSON object.

Expanding the Problems panel shows us the issue in greater detail. Nope, the properties in our mapping just don't apply to this data. This gives us an empty object ({}) in the Results panel.

Let's clear out everything in our Mapping panel to start fresh.

Introducing the $ symbol

Before we begin selecting properties from our JSON object, there's an important symbol we need to meet: $.

Let's see what this symbol does for us by adding it to the Mapping panel.

We'll see a 1:1 mapping between our JSON Input and the Results panel. It's the same data!

When used in our mapping expressions, the $ symbol refers to the JSON data of the closest enclosing object. At the top-level of our mapping, it refers to the entire JSON object we pasted in the Input panel—the full response from our endpoint. So, that's exactly what we get out in Results!

Looking closer at our JSON input, we'll see that it contains two keys: products and summary.

We can access a key on the parent object by adding a period (.) followed by the name of the key.

What changed in Results? Rather than the entire response object, we've returned the products array by itself.

This mapping returns the contents of the products key, without including the key. To bring the key back, we could add it to the beginning of the line, followed by a colon (:).

In our results, this gives us an output key ("products"), along with our selection (the "products" property on the JSON object).

Exploring shorthand syntax

What we've written thus far is the full expression of this particular mapping: we're selecting the products key and returning it under a key of the same name.

Fortunately, we can simplify this mapping! Let's see how we get the same behavior and output, but with a lot less syntax.

When it follows a colon (:), the dollar sign ($) can be dropped. This automatically selects the products property from the enclosing object, which in this case is the entire JSON object.

And when the name of our key matches the name of our selection, we can condense them into one.

Now if we add summary on its own line below products, we'll be right back where we started with our original Results object!

We've selected both properties on the input JSON, and returned them exactly—same as before.

Refining products data

We've gotten a hang of how to use the $ symbol in our mapping syntax; but in order to return the data we've specified in our schema, we need to get more granular with our selection. We'll indicate the specific properties we want to return, as well as how they map to our schema fields.

With that in mind, let's select some of the more important properties from our products array. First of all, remove summary from our Mapping panel; we're concerned just with specific product data here.

We're back to working with an object with a products key.

Let's return just the contents of the products array. Remember the syntax?

Great—we've left out the enclosing object, and returned just the data in the products array. Now how do we whittle the data for each product object even further?

To dig into each object in the array, we'll add curly braces ({}) at the end of the line.

Immediately, our Results update: and we'll see that each product in the array was replaced by an empty object!

We haven't selected anything from each product object yet—we've only replaced each with a new, empty object.

Make some space in the curly braces and add id on the next line.

Cool! So we can see that whatever we add in the curly braces after products is applied to each object in the array. The result is that each product's id is included in our output.

We can update the Mapping panel with a few more fields. Let's add name and description for each product.

With this, we've defined a selection to be applied to each object in the products array.

We're making progress on our schema! Here's what we've implemented so far.

But even though our Results panel shows the outcome of our mapping, this selection isn't actually sufficient for our schema just yet. When writing our selection for an @connect directive, we need to include each field from the schema we're providing data for. So let's keep adding onto this selection!

Practice

Key takeaways

• The $ symbol refers to the JSON data of the closest enclosing object.
• To access a property from the parent object, we can use the following syntax: $.propertyWeWant.
• With a connector's selection set, we can write a granular mapping expression that selects and optionally renames just the properties we want to return from our API.
• When the name of our key matches the name of our selection (products: products), we can condense them into one (products).

Up next

With the basics out of the way, let's expand our selection in the next lesson.