Skip to content

Commit

Permalink
Draft for Sourcing from Private APIs (#9772)
Browse files Browse the repository at this point in the history
My first draft for the docs. Appreciate feedback if there is anything that is incorrect, can be improved or additional content that could be added.

<!--
  Q. Which branch should I use for my pull request?
  A. Use `master` branch (probably).

  Q. Which branch if my change is a bug fix for Gatsby v1?
  A. In this case, you should use the `v1` branch

  Q. Which branch if I'm still not sure?
  A. Use `master` branch. Ask in the PR if you're not sure and a Gatsby maintainer will be happy to help :)

  Note: We will only accept bug fixes for Gatsby v1. New features should be added to Gatsby v2.

  Learn more about contributing: https://www.gatsbyjs.org/docs/how-to-contribute/
-->
  • Loading branch information
malcolm-kee authored and calcsam committed Nov 12, 2018
1 parent d4b7561 commit 015194c
Showing 1 changed file with 21 additions and 3 deletions.
24 changes: 21 additions & 3 deletions docs/docs/sourcing-from-private-apis.md
Expand Up @@ -2,7 +2,25 @@
title: Sourcing from Private APIs
---

This is a stub. Help our community expand it.
Gatsby allows you to pull data from headless CMSs, databases, SaaS services, public API, and your private APIs.

Please use the [Gatsby Style Guide](/docs/gatsby-style-guide/) to ensure your
pull request gets accepted.
From the Gatsby perspective, there is no difference between sourcing from a public or private API. The only difference is the availability of the API to Gatsby to query the data.

There are 3 approaches that you can use to source data from your private API:

1. If your private API is a GraphQL API, you can use [`gatsby-source-graphql`](https://www.gatsbyjs.org/packages/gatsby-source-graphql/).
2. If your private API is not a GraphQL API and you are new to GraphQL, treat the data as unstructured data and fetch it during build time, as described by the guide "[Using unstructured data](/docs/using-unstructured-data/)". However, as highlighted in the guide, this approach comes with some tradeoffs.
3. Create a source plugin, as described in the tutorial "[Source plugin tutorial](/docs/source-plugin-tutorial/)".

### Other considerations

1. If the data of your private API is updated very frequently or the expectation of the site is to be updated in real-time, it may make more sense to query the data directly during runtime.

2. If you can source the data through a plugin, consider that as an alternative to sourcing via the API. For instance, if you have access to the MongoDB database that stores the data, [`gatsby-source-mongodb`](/https://www.gatsbyjs.org/packages/gatsby-source-mongodb/) will be handy. Browse the [Gatsby Plugin Library](https://www.gatsbyjs.org/plugins/) to see what plugins that you could utilize.

3. Depending on your build process and the availability of your private API, you may need to make other adjustments accordingly.

- If your private API is only available within your company network, then you would need to expose the private API to your CI server that runs the build, else you would need to run the gatsby build in your own computer.
- You may also need to configure the endpoints of the API differently for development or production. Refer the [environment variables](/docs/environment-variables/) guide to learn how to do that.

4. To ensure your site does not show outdated data, you may want to setup an automated process to trigger the process to rebuild your site whenever the data is updated. For instance, if you host your site in Netlify, you can [make a request for its webhook to trigger a new build](https://www.netlify.com/docs/webhooks/).

0 comments on commit 015194c

Please sign in to comment.