Reading an endpoint
Zoom in on one endpoint
In the last lesson, you saw the big picture: what sections exist in API docs and where to look. Now let's zoom in on a single endpoint page and read it like a pro.
We'll use DummyJSON, a free, open API that simulates an e-commerce store with products, users, and carts. No API key needed. You can read its docs at dummyjson.com/docs/products.
Let's say you're building a product catalog page and you need to pull a list of products from the API. You've opened the docs and landed on the products endpoint.
The method and URL
The first thing on any endpoint page is the method and path. It tells you exactly what HTTP verb to use and where to send it.
This reads as: "Send a GET request to the /products path on dummyjson.com." GET means you're reading data. The base URL is https://dummyjson.com, and every endpoint in their docs builds on top of it.
Parameters: required vs. optional
Next comes the parameters table. This is where most of the useful information lives. It tells you what you can send to customize the request.
| Parameter | Type | Required | Description |
|---|---|---|---|
| limit | integer | No | Number of results to return. Default: 30 |
| skip | integer | No | Number of results to skip (for pagination). Default: 0 |
| select | string | No | Comma-separated list of fields to include (e.g. title,price) |
| sortBy | string | No | Field to sort by (e.g. title, price, rating) |
| order | string | No | Sort direction: 'asc' or 'desc' |
A few things to notice:
Required vs. optional. All parameters here are optional. That means you can call GET /products with nothing and get back the first 30 products. But if you only want 5 products sorted by price, you add ?limit=5&sortBy=price&order=asc.
Default values. When a parameter says "Default: 30", it means if you don't specify it, the API uses 30 automatically. You only need to send it if you want a different value.
Type. Tells you what kind of value to send. string means text. integer means a whole number. If you send limit=abc, the API will ignore it because it expected a number.
How parameters become a request
Let's say you want the 5 cheapest products, and you only care about the name and price. Here's how those parameters turn into a real request:
Each parameter becomes a key=value pair in the query string, joined by &. You saw this in Chapter 2 when we broke down the anatomy of a request. Now you can see how the docs translate directly into what you send.
The response schema
Endpoint pages also describe what comes back. This is the response schema, a list of fields the API returns and what they mean.
Here are the main fields for each product in DummyJSON:
| Field | Type | Description |
|---|---|---|
| id | integer | Unique product identifier |
| title | string | Product name |
| description | string | Short product description |
| price | number | Price in dollars (e.g. 9.99) |
| discountPercentage | number | Current discount (e.g. 12.96 means ~13% off) |
| rating | number | Average rating (0 to 5) |
| stock | integer | Number of items in stock |
| brand | string | Brand name |
| category | string | Product category (e.g. smartphones, groceries) |
| thumbnail | string | URL to a product image |
This tells you exactly what fields to expect in the JSON response. If your team needs the price and availability, you know those fields are price (in dollars) and stock (a count).
The response also includes pagination metadata at the top level:
{
"products": [ ... ],
"total": 194,
"skip": 0,
"limit": 30
}
The products are wrapped in a products array. total tells you how many products exist overall. skip and limit tell you which slice you're looking at. If you want the next page, you'd send ?skip=30&limit=30.
Status codes
Good docs also list what status codes the endpoint can return and what they mean:
| Status code | Meaning |
|---|---|
| 200 OK | Request succeeded. Results are in the response body. |
| 400 Bad Request | Invalid parameter (e.g. limit=abc instead of a number). |
| 404 Not Found | Endpoint or product doesn't exist (check the URL). |
| 429 Too Many Requests | You've hit the rate limit. Wait and retry. |
This is a quick reference. If you get a 429, you know it's not a bug. You're just sending too many requests and need to slow down. If you get a 400, check your parameters.
Let's test it for real
Let's try the request we built earlier: the 5 cheapest products, showing only the title and price.
You should see 5 products sorted from cheapest to most expensive. Each one only has id, title, and price because we used the select parameter to filter the fields. This is the cycle: read the docs, understand the parameters, build the request, check the response.
Now let's try without select to see the full product object:
All the fields from the response schema are there: title, price, rating, stock, brand, category, and more. The docs told you what to expect, and the response matches.
There's also a search endpoint
DummyJSON has a dedicated search endpoint at /products/search. It takes a q parameter (the search query). Let's search for "phone":
Same response structure, same fields, but filtered to products matching your search. Once you can read one endpoint, the others follow the same pattern.
Key takeaways
- Every endpoint page shows the method, URL, parameters, response schema, and status codes
- Parameters marked "required" must be included. Optional ones have defaults.
- The response schema tells you exactly what fields to expect in the JSON
- Reading an endpoint page is: method + URL, then parameters, then what comes back
- Once you can read one endpoint page, you can read any of them