Concepts - Reusing response fields

When using the UDG, there may be a situation where you want to access an API with data coming from another API. Consider the following REST APIs:

• REST API for people: https://people-api.dev/people
• REST API for a specific person: https://people-api.dev/people/{person_id}
• REST API for driver licenses: https://driver-license-api.dev/driver-licenses/{driver_license_id}

The REST API for a person will give us the following response:

{
    "id": 1,
    "name": "John Doe",
    "age": 40,
    "driverLicenseID": "DL1234"
}

And the REST API response for driver licenses looks like this:

{
    "id": "DL1234",
    "issuedBy": "United Kingdom",
    "validUntil": "2040-01-01"
}

As you can see by looking at the example responses, you could use the driverLicenseID from the People API to obtain the driver license data from the Driver License API.

You also want to design the schema so that it represents the relationship between a person and a driver license. As the person object is referencing a driver license by its ID, it means that we will need to define the driver license inside the person object as a field. Consequently, a schema representing such a relationship might look like this:

type Query {
    people: [Person]  # Data source for people
    person(id: Int!): Person  # Data Source for a specific person
}

type Person {
    id: Int!
    name: String!
    age: Int!
    driverLicenseID: ID
    driverLicense: DriverLicense  # Data Source for a driver license
}

scalar Date

type DriverLicense {
    id: ID!
    issuedBy: String!
    validUntil: Date! 
}

Defining the data source URLs

Now it’s all about defining the data source URLs.

For the field Query.people, you can simply use the URL to the API:

https://people-api.dev/people

The Query.person field needs to use its id argument to call the correct API endpoint.

See Concept: Arguments to learn more about it.

https://people-api.dev/people/{{.arguments.id}}

To retrieve the driver license data you need to be able to use the driverLicenseID from the Person object. As we defined the driver license data source on the Person object, you can now access all properties from the Person object by using the .object placeholder.

So the URL for the driver license data source would look like this:

https://driver-license-api.dev/driver-licenses/{{.object.driverLicenseID}}

Result

A query like:

{
    people {
        id
        name
        age
        driverLicense {
            id
            issuedBy
            validUntil
        }
    }
}

… will now result in something like this:

{
    "data": {
        "people": [
            {
                "id": 1,
                "name": "John Doe",
                "age": 40,
                "driverLicense": {
                    "id": "DL1234",
                    "issuedBy": "United Kingdom",
                    "validUntil": "2040-01-01"
                }
            },
            {
                "id": 2,
                "name": "Jane Doe",
                "age": 30,
                "driverLicense": {
                    "id": "DL5555",
                    "issuedBy": "United Kingdom",
                    "validUntil": "2035-01-01"
                }
            }
        ]
    }
}