4.1 Add a Remote Source
In this lesson you'll learn how to add a Remote Source to your project in order to fetch information from external third-party web services.
#Overview
This step of our Getting Started tutorial covers Remote Sources, our Content Federation utility.
A Remote Source is a custom resolver entry point for your schema that allows data to be sourced from an external third-party web service and accepts field values from other Hygraph fields as arguments.
You'll be able to add content from other systems and sources to the Hygraph API without having to migrate the content itself.
Remote content can take two shapes in your Hygraph project: a Remote Field or a Top-level Remote Field. We'll learn more about them in the following step of our tutorial.
There are many use cases where moving content into the CMS isn't possible or desirable. In our e-commerce project, we're fetching remote data for product reviews.
Let's get to it.
#Configuring our remote source
Since we want to use remote content in our project, the first step is to create a Remote Source in our project Schema. We'll connect a REST API using our DEMO Hygraph API.
Let's configure our remote source:
Configuring our remote source
We'll navigate to the Schema Builder, find the Remote Sources section in the left sidebar, and then click +Add.
We'll use the following information:
| Field | Input |
|---|---|
| Select remote source type | Custom source |
| Display Name | HyDemoAPI |
| Type | Use the radio button to select REST |
| Base URL | This field displays after selecting a type. Add http://federatethis.com/. This will be the base endpoint of our API, which Remote fields will use to send queries. |
Finally, since REST API responses can have different shapes, we need to define a structure. We'll do this by adding Custom type definitions, which will allow us to define the REST API structure using GraphQL SDL, so we can query the REST API as if it were native GraphQL.
A Schema Definition Language or SDL is a way to define the shape of data that can be queried in a GraphQL API. It describes the schema or types of data available, their relationships, and how the data can be queried. We need to tell Hygraph the shape of the data to expect and make available.
While a REST API can use multiple endpoints to return fixed data structures, a GraphQL API - not being limited to returning fixed structures - will expose just one. The custom type definitions that we add in this step allow us to specify the shape of the response coming from the API, so we can query the REST API as if it were native GraphQL.
We will be adding six custom type definitions. For each one, click on +Add custom type definition and paste the following snippets:
Your finished remote source should look like this:
Finished remote source
#Additional resources
This optional video is not part of the getting started tutorial but it shows a great step-by-step of how to configure a REST remote source!
Once you've configured a Remote Source, move on to our next lesson:
4.2 Remote Fields