Lesson 2. How to Read API Documentation

Lesson 2. How to Read API Documentation#

Goal: learn to find the information you need in API documentation without technical background.

What's in API Documentation#

Any good API documentation includes:

1. Introduction (Getting Started) — how to get started, how to get access
2. Authentication — how to prove you're allowed to use the API
3. Endpoints — list of available actions (read clients, create order, send email)
4. Parameters — what data to send in the request
5. Responses — what data the API returns (success / error)
6. Examples — ready-made request examples
7. Rate Limits — how many requests per minute / hour / day
8. Pricing — how much the API costs

How to Find the Right Action (Endpoint)#

Step 1. Decide what you want to do

Example: "I want to read the list of clients from the CRM."

Step 2. Find the section for the right resource

In the docs, look for "Clients", "Customers", or "Contacts".

Step 3. Find the right action

Actions are usually named like this:

• GET /clients — read list of clients
• GET /clients/{id} — read one client by ID
• POST /clients — create a new client
• PUT /clients/{id} — update a client
• DELETE /clients/{id} — delete a client

Step 4. Read what parameters are required

For example, POST /clients (create client) might require:

• name (required) — client name
• email (required) — client email
• phone (optional) — phone number

Step 5. Look at the request example

Good documentation always has examples. Copy the example and adapt it to your data.

Example: Stripe API Documentation#

Task: create a payment link for a client.

Step 1. Open Stripe documentation

Go to stripe.com/docs/api

Step 2. Find the "Payment Links" section

In the sidebar → Payment Links → Create a payment link

Step 3. Read the description

Creates a payment link.

Step 4. Check the parameters

• line_items (required) — list of items
  • price — price ID (created in advance)
  • quantity — quantity
• after_completion (optional) — what to do after payment

Step 5. Look at the example

POST https://api.stripe.com/v1/payment_links
{
  "line_items": [
    {
      "price": "price_1A2B3C4D5E6F",
      "quantity": 1
    }
  ]
}

Step 6. Read what the response looks like

{
  "id": "plink_1A2B3C4D5E6F",
  "url": "https://checkout.stripe.com/pay/cs_test_abc123",
  "active": true
}

You get url — that's the payment link you can send to the client.

"How to Read Documentation" Checklist#

• Open "Getting Started" or "Introduction" — understand the overall logic
• Find the authentication section — understand how to get an access key
• Find the right resource (Clients, Orders, Payments) — understand available actions
• Read the endpoint description — understand what it does
• Check the parameters — understand what data to send
• Look at the request example — copy and adapt
• Look at the response example — understand what you'll get back
• Read the "Rate Limits" section — understand how many requests you can make
• Read the "Pricing" section — understand the cost