Creating a GraphQL Remote Source Field with a simple GraphQL API

For many projects, not all of your data exists inside your content management system (CMS). While you could recreate that data or make extensive frontend calls, that can be taxing for team members or your performance budget. In this demo, we’ll create a GraphQL remote source inside a Hygraph project.

Remote sources in Hygraph let your editors relate external API data with internal Hygraph data, giving your project a single API to query for your code.

#Project set up

In this geeky example, we’re building a character for a tabletop role-playing game. In order to represent this, we’ll need a Hygraph project with a relatively simple model.

To start, we have a “Character” model that has a character’s name (Single line text field), biography (Rich text field), and avatar (Asset field). In addition to these fields, we also have a “Class” single-line text field. This lets us set things like “Fighter” or “Wizard” but doesn’t provide any additional details on what that means.

If we wanted more data, we could create a model for the classes and manually add that information. We could then associate that data with a Reference field. This sounds like a lot of overhead. Instead, we’ll grab this data from an API.

#Setting up a Remote Source

In this example, we can use a test GraphQL API that has information on Dungeons and Dragons. From spells to monsters and equipment to classes, there’s plenty of great information to be had.

To start, we’re going to head over to our Schema page in the admin and a new “remote source”.

We’ll give it a name and a prefix (if we don’t like what’s autogenerated) and then select GraphQL as our type.

For this example, the only other data we need is the GraphQL endpoint for the D&D API. We’ll leave the introspection method as post, and for this API, we don’t need a different introspection URL or headers. At this point, we’re good to click add.

We now have access to a new Remote Source field. To use it, we need to associate this new data with information in our content. To do that, we’ll add a new field to our Character model.

#Associating the GraphQL Remote Source with an index provided by the content

In the Character schema, we can create a new “GraphQL Remote source field.” Give this field a name that makes sense and an API ID to go with it.

After that, we need to define what endpoint to use. The Query section is where we’ll define which endpoint to use and pass any arguments we need to. We have a decent amount of options with this test API, but we’re going to select “Class” to associate class data with each character.

This will open up the options for this endpoint. For this API, we only have an index for our argument. From the API’s documentation, we know that it accepts a string of a class name for the index. For this, we’ll want to use the field we created for the class name. To grab dynamic data, we’ll use handlebars syntax and find the {{ doc.class }} field. From here, we can add this field, and we’re ready to test it out.

Head back over to our character content screen, and you’ll see a new field. This is a read-only field and only has a Link to preview in the API Playground. After adding content for a character — including a class string — we can click the preview link and head to the API Playground to explore.

This gives us a simple query to get the current document and grab the basic class data. Now, we can expand this to create more data for use by our frontend.

In this case, let’s get the character’s name along with some advanced data on the class selected.

query content_character_classInfo($id: ID!) {
  character: character(where: {id: $id}, stage: DRAFT) {
    name
    classInfo {
      name
      hit_die
      class_levels {
        level
        features {
          name
          desc
        }
      }
    }
  }
}

All of this data is at our fingertips from an external API with no need to copy and paste into Hygraph or set up convoluted nested queries on our frontend.

#Next steps

From here, you could take this for a spin with your own GraphQL API or extend this example further by pulling additional data from this API — maybe a spell list or equipment list.

When you’re able to mix together your various APIs, you can create some powerful solutions. We’re really excited about the possibilities of Content Federation, and we hope you take advantage of the power this offers you