GitHub API fetcher is a simplified data fetching client for GitHub's GraphQL v4 API – supporting Node.js and browsers for all types of applications: websites, scripts, data scraping, plugins etc. Works seamlessly with both JavaScript and TypeScript.
- Simple, promise-based API for common requests like user/repository/organization profiles, contributions and more. Check out the next section to get a full overview of all predefined requests.
- Full TypeScript support.
- Simple error handling with defined error types.
- Adheres to GitHub's best practices – such as dealing with abuse rate limits.
- Support for adding your own GraphQL requests.
- User profile
- Organization memberships
- Public repository ownerships
- Contributions:
- Years of contribution
- Commit contributions (monthly and yearly)
- Issue contributions (monthly and yearly)
- Pull request contributions (monthly and yearly)
- Pull request review contributions (monthly and yearly)
- Organization profile
- Repository profile
- Gist profile
Check out the documentation website for a complete overview of the API and the included models.
npm i github-api-fetcherIt's required to have a valid access token to use the client and access the GitHub API. You've the option to use your own personal access token (see this guide), or create an OAuth app and use the authenticated user's access token (see this guide). Personal access tokens is recommended while developing since it's simple to setup, while the OAuth app setup is more complicated and should be used for public use.
The following scopes is required to use all predefined requests:
- repo:status
- public_repo
- read:org
- read:user
Instead of passing the access token as an argument when using the client, it's possible to declare the access token in an environment variable with the name: GITHUB_FETCHER_API_ACCESS_TOKEN.
const { APIFetcher } = require('github-api-fetcher');
/*
* Pass access token as argument in constructor, or load from environment
* variable (see 'Configuration' section)
*/
const fetcher = new APIFetcher('SECRET-ACCESS-TOKEN');
(async () => {
const userProfile = await fetcher.user.getProfile('torvalds');
console.log(userProfile.displayName);
})();Output:
Linus Torvaldsimport { APIFetcher } from 'github-api-fetcher';
/*
* Pass access token as argument in constructor, or load from environment
* variable (see 'Configuration' section)
*/
const fetcher = new APIFetcher('SECRET-ACCESS-TOKEN');
(async (): Promise<void> => {
const userProfile = await fetcher.user.getProfile('torvalds');
// 'getProfile' returns null for non-existing users
if (!userProfile) {
console.log('User does not exist');
return;
}
console.log(userProfile.displayName);
})();Output:
Linus TorvaldsYou access the requests by the route properties on the client as shown in the example below:
const fetcher = new APIFetcher('<SECRET-ACCESS-TOKEN>');
fetcher.user // User route
fetcher.organization // Organization route
fetcher.repository // Repository route
fetcher.gist // Gist routeconst { APIFetcher, ResponseErrorType } = require("github-api-fetcher");
const fetcher = new APIFetcher('not-a-valid-token');
(async () => {
try {
const userProfile = await fetcher.user.getProfile('torvalds');
console.log(userProfile);
} catch (err) {
console.error(ResponseErrorType[err.type]);
}
})();Output:
BAD_CREDENTIALSimport { APIFetcher, RequestError, ResponseErrorType } from "github-api-fetcher";
const fetcher = new APIFetcher('not-a-valid-token');
(async () => {
try {
const userProfile = await fetcher.user.getProfile('torvalds');
// 'getProfile' returns null for non-existing users
if (!userProfile) {
console.log('User does not exist');
return;
}
console.log(userProfile.displayName);
} catch (err) {
const requestError = err as RequestError;
console.error(ResponseErrorType[requestError.type]);
}
})();Output:
BAD_CREDENTIALSFeel free to fork this repository to add, modify, delete requests and models to suit your needs.
You can build your own GraphQL queries following GitHub's schemas (documentation available here: https://developer.github.com/v4/).
Examples for custom requests can be found in the examples folder. These examples illustrates how to work with single and paged requests, as well as GraphQL fragments with plain and nested fields with aliases.
You can simply modify the base models and requests to add, modify or delete properties. Mulitple integration tests has been written to ensure all properties on the base models is being set upon parsing the response data.
You can use the NPM task, npm test, to run all tests.
This project needs your help! 💪
Please read this document. It explains how to contribute to this project.
Feel free to use the source code in any way you like – it's released under the MIT License.
I would appreciate being credited, but it's most certainly not required!
- Gustav Kofoed Clausen (@gustavclausen)
![greenkeeper[bot] avatar](https://avatars.githubusercontent.com/in/505?v=4 "greenkeeper[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent