# Remote Source configuration
With Remote Sources, it's possible to add content from other systems and sources to the Hygraph API without having to migrate the content itself.
## Add a remote source
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
[Video: Add custom Remote Source](https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9xvbajbs107w5ltraph9l)
After selecting a custom remote source, you can complete the following fields:
| Field | Input |
|-----------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `Display Name` | Enter a display name here. This name will appear in Hygraph. |
| `Prefix` | The prefix is auto-generated and will be added to all types that are created for this Remote Source to avoid name clashes. |
| `Description` | You can optionally add a description of the Remote Source here. |
| `Enable debugging` checkbox | You can enable debugging for this Remote Source, which will provide more information in case of errors. **Make sure to disable this once you finish setting up the Remote Source to avoid leaking sensitive data**. |
| `Type` | Use the radio buttons to set the type to either `REST` or `GraphQL`, depending on the type of API that this remote source will connect to. More fields will display as a result of your selection. [Check out this document's “Select a type” section to learn more about configuring REST and GraphQL types](https://hygraph.com/docs/developer-guides/remote-data/remote-sources#select-a-type). |
### Add a commercetools source
**Are you looking for a full example?:**
[Click here to view an example of how to configure a commercetools Remote Source](https://hygraph.com/docs/developer-guides/remote-data/remote-data-examples#commercetools-remote-source-configuration)
[Video: Add CommerceTools Remote Source](https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9xv9dhv3v07vx3qhunq11)
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:
| Field | Input |
|-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Authorization URL** | Enter your CommerceTools authorization URL here. Copy the **Base endpoint** in your CommerceTools credentials screen, paste it in Hygraph, and add `/oauth/token` at the end, like this: `https:///oauth/token`. |
| **Scopes** | Provide one or more scopes and click `+Add`. This is the **Scope** in the API client details view of your commercetools account. [Click here to learn more about Commercetools scopes](https://docs.commercetools.com/api/scopes). |
| **Client ID** | Enter your CommerceTools `Client ID` here. This is the **client_id** key in the API client details view of your commercetools account. Copy it and paste it in Hygraph. This is like a username. |
| **Client Secret** | Enter your CommerceTools `Client Secret` here. This is the **secret** key in the API client details view of your commercetools account. Copy it and paste it in Hygraph. This is like a password. |
Once you've completed this, you can move on to the second section, where you will configure the details of your Remote Source:
| Field | Input |
|-------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Display Name** | Enter a display name here. This name will appear in Hygraph. |
| **Prefix** | The prefix is auto-generated and will be added to all types that are created for this Remote Source to avoid name clashes. |
| **Description** | You can optionally add a description of the remote source here. |
| **Enable debugging** checkbox | You can enable debugging for this remote source, which will provide more information in case of errors. **Make sure to disable this once you finish setting up the Remote Source to avoid leaking sensitive data**. |
| **Type** | Use the radio buttons to set the type to either `REST` or `GraphQL`, depending on the type of API that this remote source will connect to. More fields will display as a result of your selection. [Check out this document's “Select a type” section to learn more about configuring REST and GraphQL types](https://hygraph.com/docs/developer-guides/remote-data/remote-sources#select-a-type). |
### Add a Commercelayer source
**Are you looking for a full example?:**
[Click here to view an example of how to configure a Commercelayer Remote Source](https://hygraph.com/docs/developer-guides/remote-data/remote-data-examples#commercelayer-remote-source-configuration)
[Video: Add CommerceLayer Remote Source](https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9xv78jbrt07w5dn43iv8h)
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:
| Field | Input |
|-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Authorization URL** | Enter your CommerceLayer authorization URL here. Copy the **Base endpoint** in your Commercelayer credentials screen, paste it in Hygraph, and add `/oauth/token` at the end, like this: `https:///oauth/token`. |
| **Scopes** | Provide one or more scopes and click `+Add`. This field is optional. [Click here to learn more about Commercelayer scopes](https://docs.commercelayer.io/core/authentication#authorization-scopes). |
| **Client ID** | Enter your CommerceLayer `Client ID` here. Copy the **Client ID** in your Commercelayer credentials screen and paste it here. |
| **Client Secret** | You can optionally enter your CommerceLayer `Client Secret` here. This field is optional. |
Once you've completed this, you can move on to the second section, where you will configure the details of your Remote Source:
| Field | Input |
|-------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Display Name** | Enter a display name here. This name will appear in Hygraph. |
| **Prefix** | The prefix is auto-generated and will be added to all types that are created for this Remote Source to avoid name clashes. |
| **Description** | You can optionally add a description of the remote source here. |
| **Enable debugging** checkbox | You can enable debugging for this remote source, which will provide more information in case of errors. **Make sure to disable this once you finish setting up the Remote Source to avoid leaking sensitive data**. |
| **Type** | Use the radio buttons to set the type to either `REST` or `GraphQL`, depending on the type of API that this remote source will connect to. More fields will display as a result of your selection. [Check out this document's “Select a type” section to learn more about configuring REST and GraphQL types](https://hygraph.com/docs/developer-guides/remote-data/remote-sources#select-a-type). |
## Select a type
### REST
[Video: Remote Source - REST](https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9xvfihv4d07vxluglw51b)
The following fields display when you select the `REST` type:
| Field | Input |
|-----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Base URL** | Enter a base URL here. All Remote Fields that connect to this Remote Source will use that base URL.
**Commercetools Base URL:** To form the base URL, you will use the **API URL** and the **project_key** from the API client details view of your commercetools account, like this: `https:////graphql`.
**Commercelayer Base URL:** Copy the **Base endpoint** in your Commercelayer credentials screen and paste it here. |
| **Headers** | Optionally, you can include HTTP headers that will be added to all API requests for all Remote Fields connected to this Remote Source. Example use cases include authorization and accepted media types. |
| **Custom type definitions** | You can now [define your custom types](https://hygraph.com/docs/developer-guides/remote-data/remote-sources#create-a-custom-type-definition) here. These provide the mapping from the API responses to the GraphQL schema. [Custom input types](https://hygraph.com/docs/developer-guides/remote-data/remote-sources#create-a-custom-input-type-definition) can optionally also be defined here. |
### GraphQL
[Video: Remote Source - GraphQL](https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9xvdjhv4507vxhy5hkgxs)
The following fields display when you select the `GraphQL` type:
| Field | Input |
|----------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Base URL** | Enter a base URL here. All Remote Fields that connect to this Remote Source will use that base URL.
**Commercetools Base URL:** To form the base URL, you will use the **API URL** and the **project_key** from the API client details view of your commercetools account, like this: `https:////graphql`.
**Commercelayer Base URL:** Copy the **Base endpoint** in your Commercelayer credentials screen and paste it here. |
| **Headers** | Optionally, you can include HTTP headers that will be added to all API requests for all Remote Fields connected to this Remote Source. Example use cases include authorization and accepted media types. |
| **Custom input type definition** | You can optionally provide an alternative introspection URL and custom headers to send to the introspection endpoint. If no separate introspection URL is provided, the base URL will be used (the default behavior for most GraphQL APIs is to allow querying and introspection on the same URL). [Custom input types](https://hygraph.com/docs/developer-guides/remote-data/remote-sources#create-a-custom-input-type-definition) can optionally also be defined here. |
| **Introspection method** | Select `GET` or `POST`.
If `GET`, we do a `GET` request and include the introspection query in the URL as a query parameter.
If `POST`, we do a `POST` request and include the introspection query in the body. |
| **Introspection URL** | If your introspection URL is different from the Remote Source URL, you can add it here. |
| **Introspection headers** | Here, you can add the headers to pass along with the request to the remote source.
Simply add a key and value pair and click `+ Add header`. |
## 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).
**Pro Tip:**
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`.
[Click here to learn more about GraphQL SDL](https://www.howtographql.com/basics/2-core-concepts)
Follow these steps to create a custom type definition:
1. While [adding a new Remote Source](https://hygraph.com/docs/developer-guides/remote-data/remote-sources#add-a-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](https://hygraph-json-to-sdl.vercel.app/) 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**
```json
{
"login": "name",
"id": 9197688,
"url": "https://api.github.com/users/name",
"repos_url": "https://api.github.com/users/name/repos",
"name": "John Doe",
"company": "@ACME",
"email": "mail@example.com"
}
```
**SDL**
```graphql
type GithubUser {
company: String
email: String
id: Int
login: String
name: String
repos_url: String
url: String
}
```
4. 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.
5. 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:
```graphql
type Product {
name: String
metaInfo: MetaInfo
slug: String
}
```
```graphql
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](https://hygraph.com/docs/developer-guides/remote-data/remote-sources#add-a-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](https://www.json2sdl.com/), which allows translating a `JSON` object to a valid SDL. Keep in mind that we are not defining a [type](https://graphql.org/learn/schema/#object-types-and-fields) here, but an [input](https://graphql.org/learn/schema/#input-types).
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:
```graphql
input productInput {
productId: String!
}
```