BA Playbook 04
First Time Working With an API
The API concepts a Business Analyst actually needs to understand.
Surya · August 8, 2026 · 4 min read · 9 practices
For Business Analysts new to integration work, BAs writing an API-related requirement for the first time, Product Owners working closely with technical teams and Anyone who nods through "endpoint" and "payload" without asking.
The first time someone puts "endpoint," "payload," "401" and "retry logic" into the same sentence, APIs can sound a lot more complicated than they actually are. Strip all of that away and an API is this: System A asks System B for something, using a contract both sides already agreed on. That's enough to start. You don't need to build one. You need to know what to ask when someone else is building one for your requirement.
01Concept 01
An API is one system asking another for something
Strip away the jargon and this is the entire idea.
Concept 01
An API is one system asking another for something
Strip away the jargon and this is the entire idea.
This is not mysterious. The system asked: "give me trade T12345." The other system returned structured data describing it. Most of what you'll deal with as a BA stays at exactly this level.
The flow
Why it helps
Once the shape feels this ordinary, the rest of the vocabulary is just naming parts of something you already understand.
GET /trades/T12345
Response:
{
"tradeId": "T12345",
"status": "MATCHED",
"quantity": 1000
}02Concept 02
Endpoint, request, response — the only three nouns you actually need
Everything else is detail on top of these three.
Concept 02
Endpoint, request, response — the only three nouns you actually need
Everything else is detail on top of these three.
At a glance
- Endpoint — the specific address you're asking
- Request — what you send, including what you're asking for
- Response — what comes back, and what it means
Why it helps
When a conversation starts drowning in acronyms, these three words are usually enough to steer it back to something you can follow.
03Concept 03
The method says what kind of ask this is
GET, POST, PUT/PATCH, DELETE aren't trivia — they tell you what the requirement does to data.
Concept 03
The method says what kind of ask this is
GET, POST, PUT/PATCH, DELETE aren't trivia — they tell you what the requirement does to data.
At a glance
- GET — read something, nothing changes
- POST — create something new
- PUT / PATCH — update something that already exists
- DELETE — remove something
Why it helps
"Does this read data or change it?" is one of the first useful questions in any API requirement discussion, and the method usually answers it in one word.
04Concept 04
Status codes are the system telling you what happened
You don't need to memorise these. You need to recognise the difference between a few of them.
Concept 04
Status codes are the system telling you what happened
You don't need to memorise these. You need to recognise the difference between a few of them.
At a glance
- 200 — worked, here's your data
- 201 — created successfully
- 400 — the request itself was wrong
- 401 — you're not signed in
- 403 — you're signed in, but not allowed
- 404 — that thing doesn't exist
- 409 — conflicts with something already there
- 500 — the other system broke, not you
Why it helps
A 401 and a 403 are different failures with different owners — one is a login problem, the other is a permission someone decided on purpose. That distinction changes who fixes it.
05Concept 05
Every field is either mandatory or optional — decide which, on purpose
A field that's silently optional is a requirement nobody actually wrote down.
Concept 05
Every field is either mandatory or optional — decide which, on purpose
A field that's silently optional is a requirement nobody actually wrote down.
At a glance
- Which fields are mandatory for the request to work at all?
- What happens if an optional field is missing from the response?
- What happens if a mandatory one is missing — reject, or guess?
Why it helps
"The field is usually there" is not the same as "the field is required." Development will build to whichever one you actually wrote.
06Concept 06
Authentication and authorisation are two different questions
"Who are you?" and "what are you allowed to do?" get lumped together constantly. They aren't the same check.
Concept 06
Authentication and authorisation are two different questions
"Who are you?" and "what are you allowed to do?" get lumped together constantly. They aren't the same check.
Compare
Authentication
Proves who is calling — a login, a token, a key.
Authorisation
Decides what that caller is allowed to do, once they're proven.
Why it helps
A caller can be authenticated and still not authorised — logged in, correctly, and still not allowed to see this particular trade.
07Concept 07
Retries and duplicates are a requirements conversation, not just a technical one
"Just retry it" is a decision, even when nobody meant it to be one.
Concept 07
Retries and duplicates are a requirements conversation, not just a technical one
"Just retry it" is a decision, even when nobody meant it to be one.
The technical word for "safe to repeat without side effects" is idempotency. You don't need the word. You need the question: if this gets sent twice by accident, does anything bad happen twice?
At a glance
- Can this request safely be sent again if it times out?
- What happens if the exact same request arrives twice?
- Could a retry create the same trade a second time?
Why it helps
This is the question that's missing from most API requirements — not because it's hard, but because it's easy to assume the answer is obviously yes.
08Concept 08
Find out who else is relying on the response before it changes
An API response is a promise to everyone already consuming it, not just to you.
Concept 08
Find out who else is relying on the response before it changes
An API response is a promise to everyone already consuming it, not just to you.
At a glance
- Who else calls this today?
- What breaks for them if a field is renamed or removed?
- Is this a new version, or a breaking change to an old one?
Why it helps
"We just need to add a field" is usually safe. "We need to change what an existing field means" usually isn't — and the difference matters to people you may never talk to directly.
09Concept 09
Plan for the moment the other system doesn't answer
A requirement that only describes a working API hasn't described the API yet.
Concept 09
Plan for the moment the other system doesn't answer
A requirement that only describes a working API hasn't described the API yet.
The shift
Why it helps
This is the gap that turns into a production incident report six months later, usually starting with "we never actually discussed what happens if..."
You don't need to build the API.
You need to know what to ask about it.
Every API requirement reduces to the same handful of questions: what's being asked for, what comes back, what happens when it fails, and who else is depending on the answer staying the same.
Take this with you
BA API Requirement Checklist
BA API REQUIREMENT CHECKLIST PURPOSE What is this API for, in one sentence? CONSUMER Who calls this API? When, and how often? ENDPOINT What is being asked for? METHOD GET, POST, PUT/PATCH, or DELETE? REQUEST FIELDS What information is sent? Which fields are mandatory? VALIDATION What makes a request invalid? RESPONSE What comes back? What does each field mean? STATUS CODES Which codes are expected? What does each one mean for this specific requirement? ERRORS What error responses are possible? What should the user see for each? AUTHENTICATION How is the caller identified? AUTHORISATION What is the caller allowed to do, specifically? TIMEOUT What happens if the response takes too long? RETRY Can the request safely be sent again? DUPLICATES What happens if the same request arrives twice? DOWNSTREAM CONSUMERS Who else relies on this response? AUDIT Does this call need to be logged? MONITORING How will we know if this API starts failing? VERSIONING Is this a new version, or a change to an existing one?
Get new playbooks first.