Reading API documentation
🎯You'll be able to
Find the base URL, endpoints, methods, sign-in, limits and error codes in API documentation before building.
🏠The everyday picture
A railway timetable tells you the station, the train number, the platform and the rules: which ticket you need and when the train runs. API documentation is a timetable for data: where to go, what to bring and what you'll get back.
📘What it really is
- Most API documentation answers the same questions. Find each before you build:
- Base URL: for example
https://api.example-courier.in/v2. - Endpoints: paths such as
/shipmentsor/shipments/{id}. - Methods:
GETto read,POSTto create,PUTorPATCHto update,DELETEto remove. - Authentication: how to prove who you are (Lesson 3).
- Parameters and body: which fields are required, their types and allowed values.
- Responses and errors: example replies and what each error code means.
-
Limits: calls per minute, page sizes, and any costs per call.
-
Look for a sandbox or test mode, so you can try calls without touching real data or money.
- Note the version (such as
/v2). Providers retire old versions, usually with notice. - Write down what you find in a short "API card" for each system: base URL, auth, key endpoints, limits, test mode, and a link to the docs.
📝A worked example
Sharma Textiles uses a regional courier, ShipFast (an example), with no n8n node. Its API card:
| Item | Value |
|---|---|
| Base URL | https://api.shipfast.example/v2 |
| Auth | API key in header X-Api-Key |
| Create shipment | POST /shipments with name, phone, address, pin code, weight in grams |
| Track | GET /shipments/{awb} returns status and scans |
| Limits | 60 calls per minute; test mode with a separate key |
| Errors | 422 means a field failed validation; the reply lists the field |
With this card you can plan the workflow before writing a single request.
🌍Where it's used
- Couriers, billing tools and local apps without ready-made nodes.
- New features of popular apps that nodes haven't added yet.
- Estimating work: a quick read of the docs tells you whether an integration takes an hour or a week.
📝Case scenario
A client asks you to connect their accounting tool, and the salesperson says "it has an API". Reading the docs, you find it only allows reading invoices, not creating them, and only on the top plan. You tell the client before agreeing a price, and suggest a CSV import as a cheaper first step.
🖱️Try it
Pick one app you use that has public API documentation. Make an API card for it with base URL, authentication, two endpoints, limits and whether it has a test mode.
⚠️Common mistakes
- Building from a blog post. Sign: fields don't match the real API. Fix: use the provider's own reference and note the version.
- Skipping the limits section. Sign: 429 errors on the first busy day. Fix: note rate limits and page sizes on your API card.
🛠️For your project
Write an API card for each simulator service from the starter README.md: base URL, endpoints, sign-in, errors. Real projects need the same card from the provider's docs.
✅Quick check
Which HTTP method is usually used to create a new record?
Show the answer
POST.
Why look for a sandbox or test mode first?
Show the answer
So you can try calls without changing real data or moving real money.