gatsby-source-custom-api

Community Plugin

gatsby-source-custom-api helps you sourcing data from any API and transform it into Gatsby nodes. Define keys you want to be transformed into image-nodes and use them with Gatsby Image.

Getting Started

Install the package with yarn or npm

yarn add gatsby-source-custom-api

Add to plugins in your gatsby-config.js

module.exports = {
    plugins: [
        {
            resolve: "gatsby-source-custom-api",
            options: {
                url: "www.my-custom-api.com"
            }
        }
    ]
};

Options

Name	Type	Description
url	object or string	`Required.` Url of your API as a string. If you have two different APIs for development and production, define an object with the keys `production` and `development`.
headers	object	Request headers. Format is the identical to that accepted by the Headers constructor. See https://www.npmjs.com/package/node-fetch
auth	object	`Optional`. Define the auth for your API in the following format: `{ username: "username", password: "password" }`.
rootKey	string	`Optional.` Name your API.
imageKeys	array	Define the keys of image objects. These must have a childkey called `url`, which is a string that defines the path to an image file. Gatsby-Images are added as childkey `local`. Default: `['image']`.
schemas	object	Define default-schemas for the objects of your API. See “Provide Default Schemas” for more information.

Provide Default Schemas

You need to provide default schemas for the arrays and objects of your API to avoid GraphQl-errors. You can provide default schemas via the prop schemas. More information: https://graphql.org/learn/schema/

// Lets assume this is the data from your API:
const exampleDataFromApi = [
    {
        url: "post-1",
        images: [
            {
                url: "image-1.jpg",
                modified: 1556752476267
            },
            {
                url: "image-2.jpg",
                modified: 1556752702168
            }
        ],
        author: {
            firstname: "John",
            lastname: "Doe"
        }
    }
];

// This is the content of your gatsby-config.js
// and what you need to provide as schema:
module.exports = {
    plugins: [
        {
            resolve: "gatsby-source-custom-api",
            options: {
                url: {
                    development: "http://my-local-api.dev", // on "gatsby develop"
                    production: "https://my-remote-api.com" // on "gatsby build"
                },
                imageKeys: ["images"],
                rootKey: "posts",
                schemas: {
                    posts: `
                        url: String
                        images: [images]
                        author: author
                    `,
                    images: `
                        url: String
                        modified: Int
                    `,
                    author: `
                        firstname: String
                        lastname: String
                    `
                }
            }
        }
    ]
};

Multiple Sources? Multiple Instances!

If you have multiple sources for your API in your project, just instantiate the plugin multiple times. Just be sure to set a different rootKey for every instance.

Connect different APIs You can connect the different APIs with @link. Find out more about this at https://www.gatsbyjs.org/docs/schema-customization/#foreign-key-fields.

module.exports = {
    plugins: [
        {
            resolve: "gatsby-source-custom-api",
            options: {
                url: "https://my-first-api.com",
                rootKey: 'authors',
                schemas:  {
                    authors: `
                        name: String
                        description: String
                    `
                }
            }
        },
        {
            resolve: "gatsby-source-custom-api",
            options: {
                url: "https://my-second-api.com",
                rootKey: 'posts',
                schemas:  {
                    posts: `
                        text: String
                        authors: authors @link(by: "name")
                    `
                }
            }
        }
    ]
};

Images

Gatsby Source Custom API automatically downloads your image-files, so you can use them with Gatsby Image.

How does it recognize images?

The default key for images is image. You can also define your own image keys with the option imageKeys. Images have to be objects containing a childkey called url, which is a string that defines the path to an image file. Gatsby-Images are added as childkey local.

What about Caching?

If your image object provides a key called modified, this key gets cached and compared every time you build or develop. If it stays the same, the already downloaded version of the image-file is used.

Transform Nodes to Pages

This is an example of how you use the required nodes to automatically generate pages: Insert the following code into the file gatsby-node.js. The sample key here is an array called posts. All array-elements can be required in GraphQl via allPosts. In this example the posts have a child-key called “url”, which defines their path and serves as marker to find them in your matching React-component (pages/post.js).

const path = require("path");

exports.createPages = async ({ graphql, actions }) => {
    const { createPage } = actions;
    const result = await graphql(`
        {
            allPosts {
                nodes {
                    url
                }
            }
        }
    `);
    return Promise.all(
        result.data.allPosts.nodes.map(async node => {
            await createPage({
                path: node.url,
                component: path.resolve("./src/pages/post.js"),
                context: {
                    // Data passed to context is available
                    // in page queries as GraphQL variables.
                    url: node.url
                }
            });
        })
    );
};

In your pages/post.js you can require the data like so:

import React from "react";
import { graphql } from "gatsby";

const Post = ({ data }) => {
    return <h1>{data.posts.title}</h1>;
};

export const query = graphql`
    query($url: String) {
        posts(url: { eq: $url }) {
            url
            title
            image {
                local {
                    childImageSharp {
                        fluid(maxWidth: 2000) {
                            ...GatsbyImageSharpFluid_withWebp
                        }
                    }
                }
                alttext
            }
        }
    }
`;

export default Post;

Replace conflicting Keys

Some of the returned keys may be transformed, if they conflict with restricted keys used for GraphQL such as the following ['id', 'children', 'parent', 'fields', 'internal']. These conflicting keys will now show up as [key]_normalized. (Thanks to gatsby-source-apiserver)

Contributing

Every contribution is very much appreciated. Feel free to file bugs, feature- and pull-requests.

❤️ If this plugin is helpful for you, star it on GitHub.