Stop 08 · Systems & Technical UnderstandingTopics · 3/9

APIs Explained for Non-Engineers

In short

Your food app shows live rider location, takes UPI payments and sends SMS updates, yet the company built none of those parts itself. APIs are how these systems talk, and BAs scope them all the time.

An API is a contract that lets two systems exchange data in a predictable format — understanding this at a conceptual level lets a BA scope integration requirements without needing to write code.

The purple blob holds a blank menu card at a serving hatch while a plate of dosa slides out to it.

Think of it like this

The Udupi restaurant menu

You can't walk into the kitchen. You order from the menu, in the way the menu says: 'one masala dosa, extra chutney'. The kitchen sends back exactly that. An API is a menu one system offers another: what you can ask for and what comes back.

Watch it happen

Your app asks a payment provider for a refund

Our system

Payment API

POST /refunds

1/5Our system sends a request to the provider's refund endpoint, following their documentation.

The big ideas

What you need to know

An API is a contract

It defines what you can request, which fields are required, and exactly what comes back.

Endpoints

Each action has an address, like /refunds. GET reads data, POST creates something, PATCH updates, DELETE removes.

Errors are part of it

Every API can fail or time out. Good requirements say what the user sees when it does.

Read the docs

Provider docs list fields, limits and errors. Skimming them early surfaces constraints before the sprint.

See it in code

Walk through the code

json

1// Request: POST /v1/refunds2{3  "payment_id": "pay_8Hk2",4  "amount": 49900,5  "reason": "item_missing"6}7 8// Response: 201 Created9{10  "id": "rfnd_31Q",11  "status": "processing"12}

1/2What we send: which payment, how much, and why. Field names come from the provider's docs.

A typical refund request and reply. Many payment APIs take amounts in the smallest unit, so 49900 paise is ₹499. A detail worth catching in requirements.

Save yourself the pain

Common mistakes

Oops

Writing 'integrate with the payment provider' as one requirement.

Do this instead

List each action needed, like create payment, refund, check status, plus what happens on each failure.

Oops

Assuming an API returns data instantly and always.

Do this instead

Ask about rate limits, timeouts and delays, like refunds that take days to settle.

Your mission

Call a public API

~15 min

Quick check

A partner's API docs say 'max 100 requests per minute'. Why should a BA care?

Go deeper

1Learn to explain what an API does using a simple analogy (like a restaurant waiter taking an order).
2Read a simple API's documentation and identify what data it sends and receives.
3Practice writing an integration requirement that references an API without over-specifying implementation.