Create a Gatsby Source Plugin to Consume an External REST API

Share this video with your friends

Send Tweet
Published 2 years ago
Updated 2 years ago

You will create your own source plugin for gatsby to get external data avaialable through a REST API into gatsby. The plugin will retrieve the data and create the gatsby nodes to make the data available through the gatsby graphql queries so you can use the data into your site.

To create this source plugin you will use some of the methods provided by the gatsby API like sourceNodes, createNode, createNodeId and createContentDigest

Matias Hernandez: [0:00] We will start by using any Gatsby site. In this case, this site was created using the starter that you can see here.

[0:06] One way to create a new plugin is by creating a new folder inside our site. We create a folder called plugins, CD into it, and then create a new site using Gatsby starter plugin. We can name this Gatsby source-buzz with API.

[0:22] We can open the file gatsby-node.js, and add our first function export sourceNodes. This will be an async function, and we can test it out by just simple console log. To see this test, we simple add this new plugin to the file gatsby-config of the original site. We execute the build script, and then we can see result in console.

[0:45] Now, we recall some library or package that allow us to fetch external data. In this example, we will use a REST API, and a node-fetch package allow us to use a very similar API, as in the browser.

[0:59] Now, let's install it, we can use it in our file. To this example where we'll use the Buzzsprout API to get the episode for some podcast. This API will return all the episodes for some podcast, but requires authentication based on a token.

[1:15] Now, we can replace our console log by using fetch to request the data. We create a new variable called response that will be equal to await fetch. As the parameters, we pass the API for the Buzzsprout podcast and add the second parameter as the headers with the token for the authorization.

[1:35] To protect our token, we will use just the env file and .env package to load it. Then, we can get JSON objects in the response by using await response.json. To test this out, we can just execute the build and check the console with our result.

[1:53] Now, that we have an array of episodes, we can make this available through Gatsby by using the createNode method provided by their API. To begin, we will add some parameters to our function starting by actions. Then, we have to loop over our array of episodes, and to do that we will use forEach. With that we will have access to each episode, and we can create a new node from Gatsby, using createNode.

[2:20] CreateNode is a function part of the actions argument to this method, which will pass all of the data that we need from our episode, and we will do that by using destructuring. Then we need to create an ID. To do that, we will use the createNodeID method. From the Gatsby API, createNodeID receive some unique string that represent each note.

[2:43] We will create a new constant called NODE_TYPE that will equal to a string podcast episode. Then, we will use this as part of the createNodeID call within a template literal to add the ID from the episode provided by the API.

[2:57] We also have to add another parameter, as the parent that will be null, the children that will be an empty array, and a require object called internal, that have some attributes like type, that will be the same NODE_TYPE.

[3:11] The content that will be a stringify object for the episode and the contentDigest that is created by using the function called createContentDigest that is available through the arguments of the sourceNode function, and that use the entire episode as an argument.

[3:27] Now, we can execute the build, but to really see if this function works, we can use gatsby develop and check the GraphQL Explorer. Here we can see there are two new queries, one called allPodcastEpisode and another call podcastEpisode. We can try one of that and see all of our episodes.

[3:48] In summary, we take the data fetches from the Buzzsprout API and create a new node for each one of that. To do this, we use some of the arguments of the sourceNode method, like createNodeID and createContentDigest.

[4:02] With this variables we createNode, the content, and the internals attribute that provides us with new queries that allow us to see the content of our podcast to be used in our site.