#Custom remote source and field configuration

In this video, Bryan uses Federate this - our collection of mock APIs and information for federated data sources in GraphQL - to show you how to add data from a remote API to your Hygraph project step-by-step.

Watch

#Configure the remote source

Navigate to the Schema builder and click on +Add next to Remote sources to create a new one. Use the following information:

Custom type definition:

Click + Add custom type definition and we'll paste the product type and products array from Federate This:

type Product {
    id: Int
    name: String
    price: Int
    description: String
    image: String
    category: String
    rating: Float
    numReviews: Int
    countInStock: Int
}

type Products {
    data: [Product]
}

We'll also add the following under Products:

type ProductMeta {
  data: Product
}

What we just added will have a data field that will bring a singular product.

Click Add at the top-right corner of your screen to create the remote source.

Once the remote source is created, you can use it to add a remote field.

#Configure remote field

After configuring our remote source, go to Schema > Query and add a top-level remote field, which will allow us to connect our products list as data directly in our API.

To add your remote field, click on REST from the right sidebar and use the following information:

Click Add at the bottom of the screen to create your remote field.

If we wanted to bring specific information into a Product model, we'd have to add a Remote Field into that model.

If you do not have a Product model yet, you can go to your Schema and click + Add next to Models and use the following information to create it:

Let's also add some fields to this model. We won't be adding price or any other information that is otherwise in out API. We will only add fields that we want to add to our data and that Editors will be able to work with.

We'll start with a single line text field that we'll use as a title:

We'll add a slug field:

We'll add a Rich Text field:

We need to associate the data in this model with the data that's in our API, and for that we'll add another single line text field, using the following information:

At this point we're ready to add our remote field. We'll scroll down the right sidebar and add a REST field using the following information:

Click Add to save your remote field.

Let's create an entry for our ProductPage model. Navigate to Content editor > ProductPage and click + Add entry.

We'll use the following information:

We'll click Save & publish and go to the API Playground to test this.

Let's run the following query:

This query brings all the information we just added in to the content entry that we created, which comes from Hygraph's data, and also includes the productData data, which comes from the API and is associated through the API ID field we added earlier.

Now imagine you also want to add your product reviews here. Federate this has sample reviews that we can use to try this. We'll go back into the schema builder and edit our remote source by adding 3 new custom type definitions.

In our remote source, we'll click on + Add new custom type definition. We'll do this three times, to add the following types:

Don't forget to click Save at the top-right of your screen to update your remote source.

Next, we're going to add this to our ProductPage model as a REST remote field. To do this, navigate to Schema builder > ProductPage, select the REST field from the right sidebar, and use the following information:

Click Add to save your remote field.

The way we have set this up allows for the product details and the reviews from that product to pull from a single API ID, which we included in the API ID field that we added to our schema earlier and to which we assigned a value in the sample entry we created.

Now we can go back to the API Playground to test this using the following query:

The response now contains the 3 sample reviews that were included in Federate This.

#Commercetools remote source configuration

#Get your commercetools keys

Before we start, there is some data we will need from your commercetools account:

Go to Settings > Developer settings > API clients. Click + Create new API client to create one from scratch, give it a name and select the scopes you need for your project.

In our example we will select the Project scope under Manage. Click Create API client at the top-right of the screen.

The resulting screen contains the information you will need to configure your remote source. Save it for later, and let's continue with the process.

#Commercetools Remote Source

Commercetools Remote Source

Navigate to the schema builder and click +Add next to Remote Sources. Use the following information to configure your remote source:

Click Add Remote Source at the bottom of the screen to save your Remote Source.

#Commercelayer remote source configuration

#Get your Commercelayer keys

Before we start, there is some data we will need from your Commercelayer account:

Go to Applications > Add new. Select a type, for this example we will select Sales Channel, give it a name, and click Get credentials.

The resulting screen contains the information you will need to configure your remote source. Save it and let's continue with the process.

#Commercelayer Remote Source

Commercelayer Remote Source

Navigate to the schema builder and click +Add next to Remote Sources. Use the following information to configure your remote source:

Click Add Remote Source at the bottom of the screen to save your Remote Source.

#Working with custom input types

In this example, we will see how we can define and use a custom input type on a Remote Field. We will be using the Github REST API, specifically the users endpoint.

#Step 1: Configure Github as Remote Source

We'll first add the Github API as a Remote Source and configure the right custom (input) types.

Set up a new remote source. If you don't know how to do this, please check out our documentation, using [https://api.github.com](https://api.github.com) as the base URL, then add a custom type with the following SDL:

type User {
  avatar_url: String
  bio: String
  blog: String
  company: String
  created_at: DateTime
  email: String
  events_url: String
  followers: Int
  followers_url: String
  following: Int
  following_url: String
  gists_url: String
  gravatar_id: String
  hireable: Boolean
  html_url: String
  id: Int
  location: String
  login: String
  name: String
  node_id: String
  organizations_url: String
  public_gists: Int
  public_repos: Int
  received_events_url: String
  repos_url: String
  site_admin: Boolean
  starred_url: String
  subscriptions_url: String
  twitter_username: String
  type: String
  updated_at: DateTime
  url: String
}

Also add a custom input type with the following SDL:

input githubInput {
  userId: String!
}

#Step 2: Set up the Remote Field

In an appropriate model, set up a REST Remote Field. In this example, we will use a model called Author and set up the Remote Field with apiId githubUserDetails. In the Remote Field config, add an input argument and select the input type to be the previously created githubInput. In the example, we will use the auto-generated API ID githubInput for the input arguments. We'll also set the field to be required since we will make the path depend on the input value.

Example - Input argument

Now configure the Remote Field's path to use the input argument. You can use the autocomplete feature in the handlebars notation for this.

Example - Remote Field path

#Step 3: Query the field

Make sure there is at least one entry for the selected model, and then head over to the API Playground. The input argument can now be used in a query in the following way:

query MyQuery {
  author(where: { id: "<some_id>" }) {
    id
    githubUserDetails(githubInput: { userId: "hygraph" }) {
      name
      bio
    }
  }
}

#Fetching a product catalog

This example shows a product content entry that fetches the product catalog from a Remote Source.

Besides the data that lives in Hygraph inside a regular model called Product - Product name, product description, etc - you can fetch a product catalog from an external API through a remote source that you added to the Product model as a Remote Field.

Remote Field example

Requests will return information in Hygraph - Product model - as well as information in the Remote Source, called myCatalogue in our Product model for this example.

The frontend could then use this information received through the Hygraph Content API to display the product page enriched with the product catalog.

#Add any REST source

This video tutorial covers adding a remote REST source into Hygraph.

Watch

Tim shows us the two ways to query a REST remote source:

• Adding a global instance for the source, so we can query it from anywhere in our code.
• Using metadata to query from content editing in the CMS.

#Top-level Remote Fields

This example uses Top-level Remote Fields to show us a product information content entry that fetches the product catalogue from an external API, unrelated to Hygraph.

Besides the data that lives in Hygraph inside a regular model called Product information - Slug, Title, Description - you can fetch a product catalogue from an external API through a Remote Source that you add to the Query model as a Remote Field.

Top-level Remote Field example

Requests will return information in Hygraph - Product model- as well as information in the Remote Source, called fieldremoteproduct in our Query model for this example.

The frontend could then use this information received through the Hygraph Content API to display the product page along with a product catalogue sourced from an external API.

#E-commerce platform

This video tutorial covers adding a remote source to Hygraph and creating Top-Level Remote Fields to pull in data from the external e-commerce platform, BigCommerce.

Watch