From bb158e950acb8485edb096fa06f0cc1208634ece Mon Sep 17 00:00:00 2001 From: Malcolm Kee Date: Wed, 7 Nov 2018 16:14:06 +0800 Subject: [PATCH 1/5] Draft for Sourcing from Private APIs 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. --- docs/docs/sourcing-from-private-apis.md | 23 ++++++++++++++++++++--- 1 file changed, 20 insertions(+), 3 deletions(-) diff --git a/docs/docs/sourcing-from-private-apis.md b/docs/docs/sourcing-from-private-apis.md index dc36662a8dc66..8d9674973d77a 100644 --- a/docs/docs/sourcing-from-private-apis.md +++ b/docs/docs/sourcing-from-private-apis.md @@ -2,7 +2,24 @@ 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 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 and there is probably no plugin that you can use to extract your data. + +There are 2 approches that you can use to source your data from your private API: + +1. treat the data as unstructured data and fetch it during build time, as described by the guide "[Using unstructured data](/docs/using-unstructured-data/)". As highlighted in the guide, this approach is more straightforward and simpler, but with its tradeoffs. +2. create your source-plugin, as described in the tutorial "[Source plugin tutorial](/docs/source-plugin-tutorial/)". + +### Other considerations + +1. It may makes more sense to query the data directly during runtime if the data of your private API updated very frequently or the expectation of the site is to be updated in real-time. + +2. If your private API is just a thin layer on top of MongoDB and you have access to the mongoDB directly, consider using [`gatsby-source-mongodb`](/https://www.gatsbyjs.org/packages/gatsby-source-mongodb/). + +3. Depending on your build process and availability of your private API, you may need to configure your `gatsby-config.js` 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 need to setup some 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 to its webhook to trigger a new build](https://www.netlify.com/docs/webhooks/). From e3d23bef8a592f52cd078dcff4391b1c75cc3205 Mon Sep 17 00:00:00 2001 From: Malcolm Kee Date: Wed, 7 Nov 2018 20:03:28 +0800 Subject: [PATCH 2/5] Sourcing from Private APIs Docs Correction Modified based on feedbacks from @LekoArts: 1. Add `gatsby-source-graphql` as an easy option if the private API is a GraphQL API. 2. Reword the consideration of alternative to be more general. --- docs/docs/sourcing-from-private-apis.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/docs/docs/sourcing-from-private-apis.md b/docs/docs/sourcing-from-private-apis.md index 8d9674973d77a..9351f9af5fd3c 100644 --- a/docs/docs/sourcing-from-private-apis.md +++ b/docs/docs/sourcing-from-private-apis.md @@ -4,22 +4,23 @@ title: Sourcing from Private APIs Gatsby allows you to pull data from headless CMSs, databases, SaaS services, public API, and your private APIs. -From 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 and there is probably no plugin that you can use to extract your data. +From 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 2 approches that you can use to source your data from your private API: +There are 3 approches that you can use to source data from your private API: -1. treat the data as unstructured data and fetch it during build time, as described by the guide "[Using unstructured data](/docs/using-unstructured-data/)". As highlighted in the guide, this approach is more straightforward and simpler, but with its tradeoffs. -2. create your source-plugin, as described in the tutorial "[Source plugin tutorial](/docs/source-plugin-tutorial/)". +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 want something straightforward and simple, 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 your source-plugin, as described in the tutorial "[Source plugin tutorial](/docs/source-plugin-tutorial/)". ### Other considerations 1. It may makes more sense to query the data directly during runtime if the data of your private API updated very frequently or the expectation of the site is to be updated in real-time. -2. If your private API is just a thin layer on top of MongoDB and you have access to the mongoDB directly, consider using [`gatsby-source-mongodb`](/https://www.gatsbyjs.org/packages/gatsby-source-mongodb/). +2. Think of alternative way to source your data instead of via the API. For instance, if you have access to the MongoDB database that store 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 availability of your private API, you may need to configure your `gatsby-config.js` accordingly. +3. Depending on your build process and availability of your private API, you may need to make other adjustment 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 need to setup some 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 to its webhook to trigger a new build](https://www.netlify.com/docs/webhooks/). +4. To ensure your site does not show outdated data, you may want to setup 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 to its webhook to trigger a new build](https://www.netlify.com/docs/webhooks/). From 1b22ecf3ba6368af21966f46d0e75915caeccb15 Mon Sep 17 00:00:00 2001 From: shannonbux <32467162+shannonbux@users.noreply.github.com> Date: Wed, 7 Nov 2018 16:16:53 -0700 Subject: [PATCH 3/5] minor edits --- docs/docs/sourcing-from-private-apis.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/docs/sourcing-from-private-apis.md b/docs/docs/sourcing-from-private-apis.md index 9351f9af5fd3c..ea309bc391508 100644 --- a/docs/docs/sourcing-from-private-apis.md +++ b/docs/docs/sourcing-from-private-apis.md @@ -10,17 +10,17 @@ There are 3 approches 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 want something straightforward and simple, 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 your source-plugin, as described in the tutorial "[Source plugin tutorial](/docs/source-plugin-tutorial/)". +3. Create your source plugin, as described in the tutorial "[Source plugin tutorial](/docs/source-plugin-tutorial/)". ### Other considerations -1. It may makes more sense to query the data directly during runtime if the data of your private API updated very frequently or the expectation of the site is to be updated in real-time. +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. Think of alternative way to source your data instead of via the API. For instance, if you have access to the MongoDB database that store 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. +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 availability of your private API, you may need to make other adjustment accordingly. +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 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 to its webhook to trigger a new build](https://www.netlify.com/docs/webhooks/). +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/). From ed9af59b1317676d1268d05f04a60c9a2a5682cf Mon Sep 17 00:00:00 2001 From: shannonbux <32467162+shannonbux@users.noreply.github.com> Date: Wed, 7 Nov 2018 16:17:58 -0700 Subject: [PATCH 4/5] a couple more minor changes --- docs/docs/sourcing-from-private-apis.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/docs/sourcing-from-private-apis.md b/docs/docs/sourcing-from-private-apis.md index ea309bc391508..beee7105cda80 100644 --- a/docs/docs/sourcing-from-private-apis.md +++ b/docs/docs/sourcing-from-private-apis.md @@ -4,13 +4,13 @@ title: Sourcing from Private APIs Gatsby allows you to pull data from headless CMSs, databases, SaaS services, public API, and your private APIs. -From 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. +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 approches that you can use to source data from your private API: +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 want something straightforward and simple, 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 your source plugin, as described in the tutorial "[Source plugin tutorial](/docs/source-plugin-tutorial/)". +3. Create a source plugin, as described in the tutorial "[Source plugin tutorial](/docs/source-plugin-tutorial/)". ### Other considerations From 7a8dcdce211ea7810339e73510a86d3a2a2c1e29 Mon Sep 17 00:00:00 2001 From: Malcolm Kee Date: Thu, 8 Nov 2018 14:18:52 +0800 Subject: [PATCH 5/5] Reword simple to be more specific Follow the guidelines of style guide, reword "if you want something simple" to "if you are new to GraphQL". --- docs/docs/sourcing-from-private-apis.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/sourcing-from-private-apis.md b/docs/docs/sourcing-from-private-apis.md index beee7105cda80..aa711b6b8634e 100644 --- a/docs/docs/sourcing-from-private-apis.md +++ b/docs/docs/sourcing-from-private-apis.md @@ -9,7 +9,7 @@ From the Gatsby perspective, there is no difference between sourcing from a publ 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 want something straightforward and simple, 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. +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