62 lines
2.8 KiB
Markdown
62 lines
2.8 KiB
Markdown
|
# GitHub Data Fetching
|
||
|
|
|
||
|
|
- [Overview](#Overview)
|
||
|
|
- [GitHub GraphQL API](#GitHub-GraphQL-API)
|
||
|
|
- [GitHub REST API](#GitHub-REST-API)
|
||
|
|
|
||
|
|
## Overview
|
||
|
|
|
||
|
|
Currently, there are three ways of getting data from GitHub to construct various parts of the docs site:
|
||
|
|
|
||
|
|
- as [external content files](content.md#external-content-files) via Git submodules of selected repos, on build time
|
||
|
|
- via GitHub's GraphQL API v4, on build time
|
||
|
|
- via GitHub's FETCH API v3, on run time
|
||
|
|
|
||
|
|
## GitHub GraphQL API
|
||
|
|
|
||
|
|
The GitHub GraphQL API integration is done through [gatsby-source-graphql](https://www.gatsbyjs.org/packages/gatsby-source-graphql/) and requires authorization.
|
||
|
|
|
||
|
|
An environment variable `GITHUB_TOKEN` needs to present, filled with a [personal access token](https://github.com/settings/tokens) with the scope `public_repo`.
|
||
|
|
|
||
|
|
For local development, you can simply [create a personal access token](https://github.com/settings/tokens) and use it in your local .env file:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
cp .env.sample .env
|
||
|
|
vi .env
|
||
|
|
# GITHUB_TOKEN=add_your_token_here
|
||
|
|
```
|
||
|
|
|
||
|
|
When running the site locally, you can use the GraphiQL client running under [localhost:8000/\_\_\_graphql](http://localhost:8000/___graphql) to explore the whole GraphQL layer of the site (not just the GitHub infos).
|
||
|
|
|
||
|
|
<img width="982" alt="screen shot 2018-11-10 at 18 41 45" src="https://user-images.githubusercontent.com/90316/48304718-66b94e80-e51e-11e8-8333-e5cadbf4d4b8.png">
|
||
|
|
|
||
|
|
This query should get you started to explore what information you can get from GitHub. All that is described in [GitHub GraphQL API](https://developer.github.com/v4/) can be used :
|
||
|
|
|
||
|
|
```graphql
|
||
|
|
query {
|
||
|
|
github {
|
||
|
|
organization(login: "oceanprotocol") {
|
||
|
|
repositories(first: 100) {
|
||
|
|
edges {
|
||
|
|
node {
|
||
|
|
name
|
||
|
|
description
|
||
|
|
url
|
||
|
|
}
|
||
|
|
}
|
||
|
|
}
|
||
|
|
}
|
||
|
|
}
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
## GitHub REST API
|
||
|
|
|
||
|
|
The GitHub GraphQL API is only queried on build time, further GitHub updates on client side need to be done through additional fetch API calls. At the moment this is done for the [repositories component](repositories.md), where the stars and forks numbers are updated on client-side.
|
||
|
|
|
||
|
|
We use [github-projects](https://github.com/oceanprotocol/github-projects) for all communications with the [GitHub REST API v3](https://developer.github.com/v3/), deployed on [Now](https://zeit.co/now).
|
||
|
|
|
||
|
|
This microservice should be used for all client-side integrations for performance and security reasons, required changes in data structure should be done over there. This service does data refetching automatically, caches results for 15min, and it has access to a secret GitHub token for making authorized API calls.
|
||
|
|
|
||
|
|
As a next step, using the REST API could be made obsolete by using some GraphQL client like [Apollo](https://www.apollographql.com) to query GitHub's GraphQL API on run time too.
|