This is a tiny reference integration that calls the GitHub API and prints a few repositories for a user.
I built it as a documentation example. The goal is to help someone go from zero to a successful call fast, and to make the failure path obvious when something goes wrong. If you only read one section, read Quickstart.
A good reference integration is not fancy. It is predictable. It makes configuration clear. It gives you an expected result. It tells you what to check when it fails.
This demo includes:
- A fast Quickstart with copy and paste commands
- Clear environment variable expectations
- Friendly errors that tell you the next step
- Node 18 or newer (uses built-in
fetch) - npm
- Install dependencies
npm install- Create your local environment file
cp .env.example .env- Edit
.envand setGITHUB_USERNAME
Example:
GITHUB_USERNAME=octocat- Run
npm run devIf it works, you will see a short list of repositories printed to the terminal.
This demo reads configuration from environment variables.
GITHUB_USERNAME (required)
GitHub username to query.
GITHUB_TOKEN (optional)
A GitHub token can help avoid rate limiting, especially if you run the demo repeatedly. For this demo, a token with basic public read access is sufficient.
.env.example shows the expected shape.
The output format is intentionally simple and readable. You should see something like:
Calling GitHub API for user: octocat
GET https://api.github.com/users/octocat/repos?per_page=5&sort=updated
Latest repos:
- hello-world | ⭐ 123 | updated 2026-01-01
https://github.com/octocat/hello-world
...
Done.
Your repo names and star counts will differ.
If something fails, start here.
If GITHUB_USERNAME is missing, the script prints help text and exits. Fix: add GITHUB_USERNAME to your .env and rerun.
If you see a 401, the token is missing or invalid. Fix: remove GITHUB_TOKEN to test without auth, or generate a new token and try again.
If you see a 403, you may be hitting GitHub rate limits for unauthenticated requests. Fix: add GITHUB_TOKEN and rerun.
If you see a 404, the username may be wrong. Fix: confirm GITHUB_USERNAME is a real GitHub user.
If you are debugging like a human:
- Print the current env var values you expect (without printing secrets)
- Log the HTTP status code and the response message
- Confirm you are on Node 18 or newer
The code is intentionally small so the README can do most of the work. In real developer docs, the documentation is often the product surface. The easiest way to reduce support burden is to make the path to success and the path to diagnosis both obvious.
If I were shipping this as part of a real public API experience, the next steps would be adding a second example that demonstrates a different workflow and adding tests that validate the error messages stay helpful.
MIT