GraphQL arguments in Connectors - GraphQL Tutorials

GraphQL meets REST, with Apollo Connectors

Introducing Apollo Connectors Project setup How Connectors work in the schema Defining a @source The @connect directive Debugging Connectors Arguments Orchestration in action Using entities with Connectors Mutations

7. Arguments

3m

(Text covers the exact same content as the video)

Overview

We have our featured listings, and one of them is really catching our eye, so how do we query just one specific listing and all its details?

In this lesson, we will:

Learn how to access GraphQL arguments in a Connector

Listing details

Here's what the mockup looks like for a listing's details:

Airlock listing details

Mapping this back to our REST API, we'll need to retrieve this data from the GET /listings/:id endpoint, passing a listing ID into the URL. We can examine the response from that endpoint here: https://airlock-listings.demo-api.apollo.dev/listings/listing-1

https://airlock-listings.demo-api.apollo.dev/listings/listing-1

Airlock listing details

REST API response

{
  "costPerNight": 120,
  "title": "Cave campsite in snowy MoundiiX",
  "locationType": "CAMPSITE",
  "description": "Enjoy this amazing cave campsite in snow MoundiiX, where you'll be one with the nature and wildlife in this wintery planet. All space survival amenities are available. We have complementary dehydrated wine upon your arrival. Check in between 34:00 and 72:00. The nearest village is 3AU away, so please plan accordingly. Recommended for extreme outdoor adventurers.",
  "id": "listing-1",
  "numOfBeds": 2,
  "closedForBookings": false,
  "photoThumbnail": "https://res.cloudinary.com/apollographql/image/upload/v1644350721/odyssey/federation-course2/illustrations/listings-01.png",
  "hostId": "user-1",
  "isFeatured": true,
  "latitude": 1023.4,
  "longitude": -203.4,
  "amenities": [
    {
      "id": "am-2",
      "category": "Accommodation Details",
      "name": "Towel"
    },
    {
      "id": "am-10",
      "category": "Space Survival",
      "name": "Oxygen"
    }
    // more amenities
  ]
}

The `listing` Connector

In the schema, let's find the Query type and add a new field called listing, which takes in an id argument of type non-nullable ID and returns a nullable Listing type.
listings.graphql
type Query {
# ...other fields
"A specific listing"
listing(id: ID!): Listing
}
Note: If you're not familiar with how to use GraphQL arguments, you can learn about them at graphql.com/learn/arguments.

Saving our changes, rover dev will now give us that expected (and helpful!) error. We know how to fix that!

error[E029]: Encountered 1 build error while trying to build a supergraph.

Caused by:
    QUERY_FIELD_MISSING_CONNECT: [listing] The field `Query.listing` has no `@connect` directive.

Let's add the @connect directive to the field, auto-completing the parameters by hitting Enter.

listings.graphql

listing(id: ID!): Listing
  @connect(
   source: ""
   http: { GET: "" }
   selection: """

   """
  )

We'll use the same source as before: listings.
listings.graphql
source: "listings"
And we're doing an HTTP GET call to /listings/:id.
listings.graphql
http: { GET: "/listings/ID???" }

But what do we put for the id? We can't hard-code an id like we did in the browser. We want to make it dynamic, pulling from the id the client would provide. So how do we get access to the value of that listing id argument here in the @connect directive?

listings.graphql

listing(id: ID!): Listing # ⬅️ Here's the id value we need!
  @connect(
  source: ""
  http: { GET: "/listings/ID???" } # ⬅️ Here's where we need it to end up!
  selection: """

  """
  )

Accessing GraphQL arguments in Connectors

args to the rescue! args gives us access to all of the field's arguments. But we'll need to prefix it with the dollar sign symbol ($), which indicates a variable in GraphQL.

Taking this schema as an example:

Example schema

type Query {
  spaceCats(name: String!, team: String!, mission: ID!): SpaceCat
}

We can access the field's arguments with $args.name, $args.team and $args.mission.

And to interpolate these values into the path in our Connector, we'll need to wrap them in curly braces ({ }).

Let's try it out!

Using `$args`

We have the start of the endpoint with the path /listings/.
listings.graphql
http: { GET: "/listings/" }
Then, because we want to access the field's id argument, we'll use $args.id, making sure to wrap it in curly braces ({}) to include it in the path.
listings.graphql
http: { GET: "/listings/{$args.id}" }
Watch out for the syntax here: the dollar sign ($) is inside the curly braces.
Great! All that's left to do is fill in our selection. The JSON response for this endpoint is actually very similar to the featuredListings Connector, a mostly one-to-one mapping, with the exception of the closedForBooking field. The mockup also shows a list of amenities that belong to the listing, but we'll tackle that in the next lesson. For now, let's keep going.
listings.graphql
selection: """
id
title
numOfBeds
costPerNight
closedForBooking: closedForBookings
"""

listing(id: ID!): Listing
  @connect(
    source: "listings"
    http: { GET: "/listings/{$args.id}" }
    selection: """
    id
    title
    numOfBeds
    costPerNight
    closedForBooking: closedForBookings
    """
  )

Checking our work

You know the drill! Save your changes and open up Sandbox.

Here we'll build a new operation, so open up a new tab, and we'll retrieve a specific listing and all of its fields.

http://localhost:4000

Variables panel

We can hit the plus button to add all the available fields in one go.

http://localhost:4000

Variables panel

We'll give this operation a new name: GetListingDetails.

query GetListingDetails($listingId: ID!) {
  listing(id: $listingId) {
    id
    title
    numOfBeds
    costPerNight
    closedForBooking
  }
}

Under the Variables section, we'll add the listingId value.

Variables

{
  "listingId": "listing-1"
}

http://localhost:4000

Variables panel

Hit Run and... we can see the details of one specific listing now! Awesome!

http://localhost:4000

GetListingDetails response

Response

{
  "data": {
    "listing": {
      "id": "listing-1",
      "title": "Cave campsite in snowy MoundiiX",
      "numOfBeds": 2,
      "costPerNight": 120,
      "closedForBooking": false
    }
  }
}

extend schema
  @link(url: "https://specs.apollo.dev/federation/v2.10", import: ["@key"])
  @link(
    url: "https://specs.apollo.dev/connect/v0.1"
    import: ["@source", "@connect"]
  )
  @source(
    name: "listings"
    http: { baseURL: "https://airlock-listings.demo-api.apollo.dev" }
  )

type Query {
  "A curated array of listings to feature on the homepage"
  featuredListings: [Listing!]!
    @connect(
      source: "listings"
      http: { GET: "/featured-listings" }
      selection: """
      id
      title
      numOfBeds
      costPerNight
      closedForBooking: closedForBookings
      """
    )

  "A specific listing"
  listing(id: ID!): Listing
    @connect(
      source: "listings"
      http: { GET: "/listings/{$args.id}" }
      selection: """
      id
      title
      numOfBeds
      costPerNight
      closedForBooking: closedForBookings
      """
    )
}

"A particular intergalactic location available for booking"
type Listing {
  id: ID!
  "The listing's title"
  title: String!
  "The number of beds available"
  numOfBeds: Int
  "The cost per night"
  costPerNight: Float
  "Indicates whether listing is closed for bookings (on hiatus)"
  closedForBooking: Boolean
}

Task!

I can see details for one specific listing 🎉

Lesson tasks

I can see details for one specific listing 🎉

Practice

Answer the following questions using the schema below:

Example schema

type Query {
  allListings(limit: Int = 10, offset: Int): [Listing!]!
}

Based on this schema, how would you access the limit argument in the allListings field's Connector?

$arguments.limit$args.limitarguments.limitargs.limit

Use the REST API JSON response below to complete the code challenge.

REST API JSON response

{
  "id": "px-m012",
  "name": "Mraza",
  "mass": 6.42
}

Code Challenge!

Complete the @connect directive for the Query.planets field. Replace the ??? instances in the http.GET path (line 20) with the correct values from the field arguments (line 17). Remember to use the $args notation to access the field arguments. Finally, refer to the resulting JSON object fields above to define the selection.

Key takeaways

To access a field's argument values from within its Connector, we can use $args. This is an object that contains the values of all of the arguments that are passed into a field when a query is run.
To interpolate the value of an argument as a URL parameter in the path, we can use curly braces. For example: http: { GET: "/listings/{$args.id}"}

Up next

We're on a roll! But we didn't quite finish up our listing details, we're still missing a listing's amenities. Let's tackle that next.

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.

field

A unit of data that belongs to a type in a schema. Every GraphQL query requests one or more fields.

type Author {
  # id, firstName, and lastName are all fields of the Author type
  id: Int!
  firstName: String
  lastName: String
}

argument

A key-value pair associated with a particular schema field that lets operations pass data to that field's resolver.

Argument values can be hardcoded as literal values (shown below for clarity) or provided via GraphQL variables (recommended).

query GetHuman {
  human(id: "200") {
    name
    height(unit: "meters")
  }
}

arguments

A key-value pair associated with a particular schema field that lets operations pass data to that field's resolver.

Argument values can be hardcoded as literal values (shown below for clarity) or provided via GraphQL variables (recommended).

query GetHuman {
  human(id: "200") {
    name
    height(unit: "meters")
  }
}

field

A unit of data that belongs to a type in a schema. Every GraphQL query requests one or more fields.

type Author {
  # id, firstName, and lastName are all fields of the Author type
  id: Int!
  firstName: String
  lastName: String
}

query

A request for specific data from a GraphQL server. Clients define the structure of the response, enabling precise and efficient data retrieval.

argument

A key-value pair associated with a particular schema field that lets operations pass data to that field's resolver.

Argument values can be hardcoded as literal values (shown below for clarity) or provided via GraphQL variables (recommended).

query GetHuman {
  human(id: "200") {
    name
    height(unit: "meters")
  }
}

query

A request for specific data from a GraphQL server. Clients define the structure of the response, enabling precise and efficient data retrieval.

GraphQL

An open-source query language and specification for APIs that enables clients to request specific data, promoting efficiency and flexibility in data retrieval.

arguments

A key-value pair associated with a particular schema field that lets operations pass data to that field's resolver.

Argument values can be hardcoded as literal values (shown below for clarity) or provided via GraphQL variables (recommended).

query GetHuman {
  human(id: "200") {
    name
    height(unit: "meters")
  }
}

field

A unit of data that belongs to a type in a schema. Every GraphQL query requests one or more fields.

type Author {
  # id, firstName, and lastName are all fields of the Author type
  id: Int!
  firstName: String
  lastName: String
}

argument

A key-value pair associated with a particular schema field that lets operations pass data to that field's resolver.

Argument values can be hardcoded as literal values (shown below for clarity) or provided via GraphQL variables (recommended).

query GetHuman {
  human(id: "200") {
    name
    height(unit: "meters")
  }
}

GraphQL

An open-source query language and specification for APIs that enables clients to request specific data, promoting efficiency and flexibility in data retrieval.

arguments

A key-value pair associated with a particular schema field that lets operations pass data to that field's resolver.

Argument values can be hardcoded as literal values (shown below for clarity) or provided via GraphQL variables (recommended).

query GetHuman {
  human(id: "200") {
    name
    height(unit: "meters")
  }
}

directive

A GraphQL annotation for a schema or operation that customizes request execution. Prefixed with @ and may include arguments. For example, the @lowerCase directive below can define logic to return the username field in lowercase:

type User {
  username: String! @lowerCase
}

field

A unit of data that belongs to a type in a schema. Every GraphQL query requests one or more fields.

type Author {
  # id, firstName, and lastName are all fields of the Author type
  id: Int!
  firstName: String
  lastName: String
}

argument

A key-value pair associated with a particular schema field that lets operations pass data to that field's resolver.

Argument values can be hardcoded as literal values (shown below for clarity) or provided via GraphQL variables (recommended).

query GetHuman {
  human(id: "200") {
    name
    height(unit: "meters")
  }
}

directive

A GraphQL annotation for a schema or operation that customizes request execution. Prefixed with @ and may include arguments. For example, the @lowerCase directive below can define logic to return the username field in lowercase:

type User {
  username: String! @lowerCase
}

field

A unit of data that belongs to a type in a schema. Every GraphQL query requests one or more fields.

type Author {
  # id, firstName, and lastName are all fields of the Author type
  id: Int!
  firstName: String
  lastName: String
}

arguments

A key-value pair associated with a particular schema field that lets operations pass data to that field's resolver.

Argument values can be hardcoded as literal values (shown below for clarity) or provided via GraphQL variables (recommended).

query GetHuman {
  human(id: "200") {
    name
    height(unit: "meters")
  }
}

variable

A placeholder for dynamic values in an operation allowing parameterization and reusability in requests. Variables can be used to fill arguments or passed to directives.

query GetUser($userId: ID!) {
  user(id: $userId) {
    firstName
  }
}

In the query above, userId is a variable. The variable and its type are declared in the operation signature, signified by a $. The type of variable is a non-nullable ID. A variable's type must match the type of any argument it's used for.

GraphQL

An open-source query language and specification for APIs that enables clients to request specific data, promoting efficiency and flexibility in data retrieval.

field

A unit of data that belongs to a type in a schema. Every GraphQL query requests one or more fields.

type Author {
  # id, firstName, and lastName are all fields of the Author type
  id: Int!
  firstName: String
  lastName: String
}

arguments

A key-value pair associated with a particular schema field that lets operations pass data to that field's resolver.

Argument values can be hardcoded as literal values (shown below for clarity) or provided via GraphQL variables (recommended).

query GetHuman {
  human(id: "200") {
    name
    height(unit: "meters")
  }
}

field

A unit of data that belongs to a type in a schema. Every GraphQL query requests one or more fields.

type Author {
  # id, firstName, and lastName are all fields of the Author type
  id: Int!
  firstName: String
  lastName: String
}

argument

A key-value pair associated with a particular schema field that lets operations pass data to that field's resolver.

Argument values can be hardcoded as literal values (shown below for clarity) or provided via GraphQL variables (recommended).

query GetHuman {
  human(id: "200") {
    name
    height(unit: "meters")
  }
}

field

A unit of data that belongs to a type in a schema. Every GraphQL query requests one or more fields.

type Author {
  # id, firstName, and lastName are all fields of the Author type
  id: Int!
  firstName: String
  lastName: String
}

operation

A single query, mutation, or subscription that clients send to a GraphQL server to request or manipulate data.

fields

A unit of data that belongs to a type in a schema. Every GraphQL query requests one or more fields.

type Author {
  # id, firstName, and lastName are all fields of the Author type
  id: Int!
  firstName: String
  lastName: String
}

fields

A unit of data that belongs to a type in a schema. Every GraphQL query requests one or more fields.

type Author {
  # id, firstName, and lastName are all fields of the Author type
  id: Int!
  firstName: String
  lastName: String
}

operation

A single query, mutation, or subscription that clients send to a GraphQL server to request or manipulate data.