APIs for business analysts

What an API is, in plain English

An API (Application Programming Interface) is an agreed way for one piece of software to talk to another. Picture a restaurant. You (the app) do not walk into the kitchen (the other system). A waiter takes your order in a standard format and brings back a standard answer. The API is the waiter and the menu: it says what you may ask for and what you will get back.

Most business systems you will meet use REST APIs over the web. You send a request to an address (an endpoint) using a verb (an HTTP method), and the server sends back a response containing a number (a status code) and usually some data in a text format called JSON.

When two systems exchange data automatically (for example a webshop telling a courier about a new parcel), that is an integration, and an API is usually how it happens.

Why a business analyst needs to understand APIs

Modern projects rarely build one system alone. They connect payments, identity, CRM, shipping, banking and reporting systems. Somebody must say precisely what is exchanged, when, and what happens when it fails. That somebody is often the business analyst. Vague API requirements cause some of the most expensive rework: wrong fields, missing error handling, and surprises at go-live. A BA who understands APIs can:

• Read vendor documentation and tell the team what is possible.
• Write requirements that name the fields, rules and error cases.
• Test with a simple tool and attach real request/response evidence to a ticket.
• Spot business risks: rate limits, missing data, unclear ownership of a field.

You do not need to code. You do need to be comfortable reading a small piece of JSON without panicking.

Anatomy of a request and response

FleetArc Logistics is a fictional courier company. Its customers' systems ask FleetArc where a parcel is. Here is the request:

GET /v1/shipments/FA-20931 HTTP/1.1
Host: api.fleetarc.example
Authorization: Bearer <token>
Accept: application/json

Read it from the top. GET is the method: "read something". /v1/shipments/FA-20931 is the endpoint path: version 1 of the API, the shipments collection, one shipment identified by FA-20931. The headers add context: who is asking (the token proves identity) and what format is wanted. A successful response looks like this:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "shipmentId": "FA-20931",
  "status": "in_transit",
  "origin": {"city": "Rotterdam", "country": "NL"},
  "destination": {"city": "Leeds", "country": "GB"},
  "estimatedDelivery": "2026-10-14",
  "parcels": [
    {"parcelId": "P-1", "weightKg": 4.2},
    {"parcelId": "P-2", "weightKg": 1.1}
  ]
}

JSON is built from fields (name and value pairs), objects (curly braces holding fields) and lists (square brackets). Strings are in quotes, numbers are not. Check the types: weightKg is a number, estimatedDelivery is a text date in year-month-day form.

The common methods map to everyday actions:

Status codes you will meet every week

The number at the top of a response tells you in a glance what happened. Groups matter more than memorising every number: 2xx means success, 4xx means the caller made a mistake, 5xx means the server had a problem. The Mozilla reference for HTTP status codes lists them all, and we cover the important ones in detail in REST API status codes for business analysts.

Here is a creation request that fails, because a required field is missing:

POST /v1/shipments HTTP/1.1
Content-Type: application/json

{
  "destination": {"city": "Leeds", "country": "GB"},
  "parcels": [{"weightKg": 4.2}]
}

HTTP/1.1 422 Unprocessable Content
Content-Type: application/json

{
  "error": "validation_failed",
  "message": "origin is required",
  "fields": [{"field": "origin", "rule": "required"}]
}

The request was understood, but the content broke a business rule, so the API returns a 4xx code with a machine-readable explanation. A good API requirement states these cases, including the wording or error codes the caller will see.

Worked example: writing an API requirement

The business need: "Shop owners want to see parcel status inside their own order screen without logging in to FleetArc." The BA turns this into a precise requirement.

Business requirement. A customer's system can retrieve the current status and estimated delivery date of a shipment.

Functional requirements (API).

1. The API shall expose GET /v1/shipments/{shipmentId}.
2. The caller must send a valid access token; otherwise the API returns 401.
3. A caller may read only shipments belonging to their own account; otherwise the API returns 404 (not 403, so shipment IDs are not revealed).
4. The response shall contain shipmentId, status, destination city and country, estimatedDelivery and parcels.
5. status shall be one of: booked, picked_up, in_transit, out_for_delivery, delivered, exception.
6. If the shipment ID does not exist, return 404 with error code shipment_not_found.
7. If more than 60 requests arrive from one account in a minute, return 429 with a Retry-After header.

Non-functional requirements. 95 percent of lookups answer within 1 second under normal load; every request is logged with a request ID but not with personal addresses. (These numbers are examples for the exercise; real targets come from the business.) See non-functional requirements for why these matter.

Notice the structure: method and path, who may call, what is returned, allowed values, and each failure with its code. A developer can build from this, and a tester can derive test cases directly. The set of agreed requests and responses is often written up as an API contract.

Field mapping between systems

When two systems exchange data, their field names, formats and meanings rarely match. A field mapping table records how to translate. For the webshop's order screen:

Always ask the awkward questions: what if a field is empty, what time zone does a timestamp use, are amounts in cents or whole currency units, and who is the master of the data if the two systems disagree?

Security, limits and versions: the non-obvious requirements

Beyond fields and codes, every API has rules that shape the business solution. Ask about each of these early, because they are costly to discover late.

• Authentication proves who is calling. Common forms are API keys and tokens. Ask how credentials are issued, who owns them, how often they expire and what happens to the integration when they do. Never store or share real credentials in tickets, slides or chat.
• Authorisation decides what a caller may do once identified. In the FleetArc example, a shop may read only its own shipments. Write the rule down for each endpoint.
• Rate limits cap how many calls are allowed per minute or day. If your process needs to refresh 20,000 parcels every hour, you must check whether the limit allows it, or whether the provider offers a bulk endpoint or notifications instead.
• Webhooks reverse the direction: instead of you repeatedly asking "has the status changed?", the provider calls your system when something happens. They reduce traffic but add questions about retries and duplicate messages.
• Versioning lets a provider improve an API without breaking existing users. The /v1/ in the path is a version. Ask how long old versions are supported and who will be told about changes.
• Idempotency is a long word for "doing it twice has the same effect as doing it once". If a booking request times out and the caller retries, will FleetArc create two shipments? Good APIs let the caller send a unique key so duplicates are ignored. This is a real business risk for payments and orders.
• Sandbox versus production: practise and test against a sandbox with fake data. Agree how and when the switch to production happens.

A short "integration checklist" attached to the requirement, listing these seven points with the answer for your project, prevents a surprising number of go-live problems.

Step by step: how to approach any API task

1. Start from the business goal and the user journey, not the endpoint list.
2. Read the vendor documentation for the relevant endpoints. Note authentication, limits and versioning.
3. Try a call in a sandbox with a simple API testing tool and keep the real response as evidence.
4. List the data: which fields do you need, what are their types and allowed values?
5. List the failure cases: bad input, no permission, not found, timeout, system down, duplicate request.
6. Write requirements and mapping using the patterns above, then review them with a developer.
7. Turn them into test cases and acceptance criteria in your tickets.

Common mistakes

• ✅ Specify error cases and codes. ⚠️ Writing only the happy path.
• ✅ Give allowed values for status-like fields. ⚠️ "Status: text" with no list.
• ✅ Show example JSON with realistic data. ⚠️ Describing fields only in prose.
• ✅ State who owns each piece of data. ⚠️ Letting two systems both edit the same field.
• ✅ Ask about limits, retries and what happens when the other system is down. ⚠️ Assuming the integration is always available.
• ✅ Keep secrets (tokens, keys) out of tickets and screenshots. ⚠️ Pasting a live token into a shared document.
• ✅ Check the API version. ⚠️ Specifying against documentation for an older version.

Reader exercise

Imagine CartNest wants to show a customer's loyalty points from a points service. Write: (1) the endpoint and method, (2) example success JSON with at least four fields, (3) three failure cases with status codes, and (4) a four-row field mapping table. Check each field has a type and that you have said what happens when the points service is unavailable.

How to practise APIs in the BA Lab

Stage 7 of the BA Lab, APIs and integration, gives you a mock API console inside a fictional company project. You send requests, read JSON, judge whether a status code is right and write an API requirement, and the checks explain mistakes. It is a safe practice environment with made-up data. The pricing page shows which packages include it, and the free demo shows the Lab's style. If you want to understand the data behind an API, pair this with SQL for business analysts.

Frequently asked questions