Reading API Documentation
Base URL, endpoints, parameters, headers, request body, and response schema
Skills taught: api.reading-docs, api.base-url, api.path-params, api.query-params, api.request-body-schema
Anatomy of an API endpoint
───────────────────────────────────────────────────────
GET /repos/{owner}/{repo}/issues
───────────────────────────────────────────────────────
Base URL: https://api.github.com
Full URL: https://api.github.com/repos/facebook/react/issues
Path Parameters (required, part of URL):
owner string The account owner of the repository
repo string The name of the repository
Query Parameters (optional, after ?):
state string open | closed | all default: open
labels string Comma-separated list of label names
sort string created | updated | comments default: created
page integer Page number default: 1
per_page integer Results per page (max 100) default: 30
Headers:
Authorization: Bearer {personal_access_token} (optional for public repos)
Accept: application/vnd.github+json (recommended)
Response: 200 OK
Array of Issue objects:
[
{
"id": 12345,
"number": 28847,
"title": "Fix memory leak in hooks",
"state": "open",
"user": { "login": "alice", "id": 100 },
"labels": [{ "name": "bug", "color": "d73a4a" }],
"created_at": "2026-01-15T10:00:00Z",
"body": "When using useEffect..."
}
]
───────────────────────────────────────────────────────
// Translating the docs above into actual fetch() calls
const BASE = 'https://api.github.com';
const TOKEN = process.env.GITHUB_TOKEN; // optional for public repos
// GET /repos/{owner}/{repo}/issues?state=open&per_page=5
const owner = 'facebook';
const repo = 'react';
// Build query string from an object (cleaner than manual string)
const params = new URLSearchParams({
state: 'open',
sort: 'created',
per_page: '5',
});
const url = `${BASE}/repos/${owner}/${repo}/issues?${params}`;
console.log('URL:', url);
// → https://api.github.com/repos/facebook/react/issues?state=open&sort=created&per_page=5
const res = await fetch(url, {
headers: {
'Accept': 'application/vnd.github+json',
'Authorization': TOKEN ? `Bearer ${TOKEN}` : undefined,
},
});
if (!res.ok) {
const err = await res.json().catch(() => ({ message: res.statusText }));
throw new Error(`GitHub API ${res.status}: ${err.message}`);
}
const issues = await res.json();
console.log(`Found ${issues.length} open issues`);
issues.forEach(i => console.log(` #${i.number}: ${i.title}`));
// Check rate limit from response headers
console.log('Remaining requests:', res.headers.get('x-ratelimit-remaining'));
console.log('Resets at:', new Date(res.headers.get('x-ratelimit-reset') * 1000));
Frequently Asked Questions
How do I find an API's documentation?
Search for '{service name} API docs' or '{service name} developer docs'. Most major services have a developer portal (stripe.com/docs, docs.github.com, openweathermap.org/api). Look for an 'API Reference' section — this lists all endpoints with parameters and response schemas. If they publish an OpenAPI spec (often linked as openapi.json or swagger.yaml), you can import it into tools like Postman or Insomnia for interactive testing.