#Add a remote source

Remote Sources - Select a type

The first step to adding a remote source to your project is selecting the type. You can create a custom source or use a pre-built one. Hygraph offers pre-built remote sources for CommerceTools and CommerceLayer.

1. Navigate to the Schema Builder.
2. In the left sidebar, find the Remote Sources section at the bottom of the list, then click +Add.
3. Use the selection boxes at the top of the screen to select a remote source type:
   • Custom
   • CommerceTools
   • CommerceLayer

#Add a custom source

After selecting a custom remote source, you can complete the following fields:

#Add a commercetools source

After selecting a CommerceTools Remote Source, you will find that the screen now contains two distinct sections for you to complete. The first section is the OAuth configuration for CommerceTools:

Once you've completed this, you can move on to the second section, where you will configure the details of your Remote Source:

#Add a Commercelayer source

After selecting a CommerceLayer remote source, you will find that the screen now contains two distinct sections for you to complete. The first section is the OAuth configuration for CommerceLayer:

Once you've completed this, you can move on to the second section, where you will configure the details of your Remote Source:

#Select a type

#REST

The following fields display when you select the REST type:

#GraphQL

The following fields display when you select the GraphQL type:

#Create a custom type definition

When connecting to a remote REST API, you will have the option to define a Custom Type Definition, which allows you to specify the shape of the response coming from the API. It will allow you to query the REST API as if it were native GraphQL.

These Custom Type Definitions use GraphQL SDL (Schema Definition Language).

Follow these steps to create a custom type definition:

1. While adding a new Remote Source or editing an existing one, scroll down to Custom Type Definitions and click +Add.

2. You can use our JSON to SDL converter tool to transform the JSON response from your API into valid GraphQL SDL. You might need to make a few tweaks to the generated SDL, especially changing the JSON type to Json (note the difference in casing).

   Here's an example of what that would look like:

   JSON

   SDL

3. Add the SDL for your custom type to the input field. It's possible to add multiple types in a single input field, after saving the types will be moved to separate fields.

4. Click Create or Save on the top right corner.

Custom types also support nesting, so they can make use of another type, as shown below:

type Product {
  name: String
  metaInfo: MetaInfo
  slug: String
}

type MetaInfo {
  createdAt: DateTime
  createdBy: String
  currency: String
}

In this example, the custom Product type makes use of another custom type MetaInfo.

#Create a custom input type definition

Remote Fields also allow you to pass along input parameters to your Remote Source endpoint. This can be useful if the identifiable information for the remote data isn't kept in Hygraph, but defined on a request basis. This is relevant for both the REST and GraphQL Remote Sources.

To create such a definition and to use it in a query, you will need to follow these steps:

1. While adding a new Remote Source, or editing an existing one, scroll down to Custom Input Type Definition and click on +Add.

2. Similar to the Custom Types, you need to use the GraphQL Schema Definition Language (SDL) to define what the input parameter will look like. A tool that could be used here is JSON2SDL, which allows translating a JSON object to a valid SDL. Keep in mind that we are not defining a type here, but an input.

   Let's take an example of passing a productId to our remote API, that will be used as an input argument. The SDL would look like this:

   input productInput {
     productId: String!
   }

   Copy