What API docs look like
The instruction manual for every API
You know how to send API requests, read JSON responses, and authenticate. But when you sit down to work with a new API, how do you know what endpoints exist, what parameters to send, or what the response will look like?
That's what API documentation is for. It's the instruction manual that tells you everything the API can do and exactly how to use it.
Think of it like a restaurant menu. You wouldn't walk into a restaurant and shout "give me food." You'd look at the menu, see what's available, check the options (medium or well-done?), and place a specific order. API docs are the menu.
The sections you'll find everywhere
Every API doc follows roughly the same structure. Once you've seen it two or three times, you can navigate any doc. Here are the sections that show up again and again.
1. Base URL
This is the starting point for all requests. Every endpoint builds on top of it.
Stripe's base URL is https://api.stripe.com. Twilio's is https://api.twilio.com. NewsAPI's is https://newsapi.org. You'll see the base URL at the very top of the docs, and every endpoint starts with it.
2. List of endpoints
This is the core of the docs. It lists every operation you can perform: get a list of users, create an order, delete a subscription. Usually organized by resource (Users, Orders, Products).
| Method | Endpoint | Description |
|---|---|---|
| GET | /v1/customers | List all customers |
| GET | /v1/customers/:id | Retrieve a customer |
| POST | /v1/customers | Create a customer |
| DELETE | /v1/customers/:id | Delete a customer |
This should look familiar from Chapter 3. The docs lay out the exact method and path for each operation, plus a short description.
3. Authentication section
Docs always explain how to authenticate. This section tells you what type of credentials you need (API key, token, OAuth), where to get them, and where to put them in your request.
For example, Stripe's docs tell you to send your API key as a Bearer token:
Other APIs (like NewsAPI) use a query parameter instead. The docs tell you which approach to use.
4. Parameters
For each endpoint, the docs list what parameters you can send. Some are required (the request fails without them), others are optional (they let you fine-tune the results).
Here's what the parameter table looks like for NewsAPI's /everything endpoint (a search endpoint for news articles):
| Parameter | Type | Required | Description |
|---|---|---|---|
| q | string | Yes | The search query (e.g. 'bitcoin', 'Apple') |
| from | string | No | Start date (e.g. 2024-01-15) |
| sortBy | string | No | Sort order: relevancy, popularity, or publishedAt |
| pageSize | integer | No | Number of results per page (max 100) |
This is the kind of table you'll see on every endpoint page. It tells you the name, the data type, whether it's required, and what it does. You'll use this exact endpoint later in this chapter.
5. Example requests and responses
Good docs show you complete examples: here's a request you can copy, and here's what the response looks like. This is often the most useful section because you can take the example, swap in your own values, and run it.
Real docs follow this pattern
Let's map this to some APIs you might encounter at work:
| API | Base URL | Auth method | What it does |
|---|---|---|---|
| Stripe | https://api.stripe.com | Bearer token (API key) | Payments, subscriptions, invoices |
| Twilio | https://api.twilio.com | Basic auth (account SID + token) | SMS, voice calls, verification |
| NewsAPI | https://newsapi.org | Query parameter (apiKey=...) | News headlines and articles |
| OpenAI | https://api.openai.com | Bearer token (API key) | AI text generation, image creation |
Different APIs, different purposes, but the docs all follow the same structure: base URL, endpoints, auth, parameters, examples.
Where to look first
When you open API docs for the first time, here's a practical order:
- Authentication. Find how to get credentials and where to put them. Nothing works without this.
- List of endpoints. Scan the sidebar or table of contents. Find the resource you care about (users, orders, messages).
- The specific endpoint. Click into it. Read the parameters table and look at the example request.
- Try the example. Copy it, plug in your credentials, and run it.
You don't need to read the whole doc cover to cover. You navigate to what you need, just like you don't read a restaurant menu front to back. You go to the section you want.
Key takeaways
- API docs are the instruction manual. They tell you what the API can do and how to use it.
- Every doc has the same core sections: base URL, endpoints, authentication, parameters, and examples.
- You don't read docs top to bottom. You scan for the section you need, starting with authentication.
- Once you've navigated one API doc, the pattern is the same everywhere.