How to Analyze an API: The Analyst's Method Before Anyone Writes Integration Code

API analysis answers one question before anyone writes integration code: can this API support our business process, with our data, under failure, at our volume, and through its future changes? The method is five lenses applied in order, capability, data, behavior, limits, and change, with every finding backed by both the documentation and a request you actually sent.

To analyze an API: map each step of the business process to an endpoint or event; map each of your data fields to the API’s fields, units, and formats; send requests that fail on purpose to learn the error and status model; do the arithmetic on rate limits and pagination against your volumes; and check how versions, deprecations, and credentials are managed. Record it all in a fit-gap worksheet, then make a decision on every gap before the build starts. Skipping this is how teams discover in system integration testing that the API cannot do the one thing the business case depended on.

APIs for Analysts, part 3 of 8. Previous: Part 2, your first API collection in Bruno and Postman. Next: Part 4, how to document an API. All parts: series overview.

I use Stripe as the running example below because its documentation and sandbox are public, so every claim can be checked and every request can be sent by you. The same method applies unchanged to a core banking API, a card processor, or an internal payments service. The structured requirement work that comes out of an analysis like this is what From Vague BR to Functional Requirements walks through end to end.

What does analyzing an API actually mean?

It means evaluating an API against a specific need, not describing the API in general. Reading an API reference from top to bottom tells you what the API offers. Analysis starts from the other end: what the business must do, and whether the API lets it.

Lens	The question	Where the answers hide
1. Capability	Can it do each step of our process?	Endpoints, webhooks, and what is missing between them
2. Data	Can it carry our data, in our units and formats?	Schemas, field lengths, enums, metadata limits
3. Behavior	What happens when things go wrong?	Status models, error objects, retries, idempotency
4. Limits	Does it fit our volume, timing, and non-functional needs?	Rate limits, pagination, timeouts, status pages
5. Change	Will it keep working, and who controls that?	Versioning, changelogs, deprecation policy, credentials

The order matters. A capability gap can kill the integration outright, so it comes first. A data gap usually means a transformation. A behavior gap means extra design. A limit gap means a delivery constraint. Change risks go into the run book and the contract.

The deliverable is always the same: a worksheet with evidence and decisions, plus a collection of the requests you sent to produce it. Both matter. The worksheet convinces the steering committee; the collection saves the integration team their first week.

Step 1: How do you map the business process to endpoints?

Write the business process as steps, then find the endpoint or event that supports each step. The gaps show up as rows with nothing in the second column, or something that only nearly fits.

Here is a capability map for a marketplace taking card payments and handling partial refunds through Stripe:

Business step	API capability	Evidence	Fit
Save the buyer for repeat purchases	POST /v1/customers	Docs + request sent, cus_ id returned	Fit
Take a card payment	POST /v1/payment_intents with confirm=true	Docs + request sent with test card pm_card_visa, status succeeded	Fit
Know the payment is final	payment_intent.succeeded webhook	Docs + event captured with Stripe CLI	Fit, asynchronous
Partially refund from the ops console	POST /v1/refunds with amount	Docs + request sent	Fit
Capture a free-text refund reason for ops	reason accepts only duplicate, fraudulent, requested_by_customer	Docs + request with other value rejected	Gap
Reconcile daily against the bank	GET /v1/balance_transactions, paginated	Docs + request sent	Fit, with volume check
Handle a chargeback	charge.dispute.created webhook	Docs	Fit, not yet exercised

The refund reason row is the kind of gap that sinks projects quietly. The ops team’s requirement said “record why we refunded”, and the refund API has a three-value enum. The API does allow custom metadata key-value pairs on the refund, so the gap has a workaround, but that is a design decision, and somebody has to make it and write it down before the ops console is built.

Two rules for this step. First, the Evidence column must say what you did, not just link a doc page. “Docs + request sent” beats “see docs” every time. Second, webhooks count as capabilities. Many business steps, such as “know the payment is final”, are only answered asynchronously, and an analysis that lists only endpoints misses half the integration.

Step 2: How do you map data field by field?

List every field your process needs to send or receive, and map each one to the API’s field with its type, format, unit, and length. This is where most integration defects are born, because the endpoints exist but the data does not quite fit.

Our field	Our format	API field	API format	Transformation	Risk
Order total	Decimal 20.00	amount	Integer in smallest currency unit, 2000	Multiply by 100; not for zero-decimal currencies such as JPY	High
Currency	USD	currency	Lowercase ISO code, usd	Lowercase	Low
Order reference	String, up to 64 chars	metadata[order_ref]	Metadata value, up to 500 chars	None	Low
Refund reason (free text)	String, up to 1,000 chars	metadata[ops_reason]	Metadata value, up to 500 chars	Truncate or reject over 500	Medium
Created at	ISO 8601 2026-09-15T10:42:00Z	created	Unix timestamp in seconds	Convert	Medium
Customer email	String	email on the Customer	String	None	Low

Stripe’s documentation states that metadata supports up to 50 keys, with key names up to 40 characters and values up to 500 characters. That one limit turned “store the refund reason in metadata” from a clean workaround into a truncation rule that needs a requirement, a UI character counter, and a test case.

The amount row is the classic. An analyst who writes “send the order total” without the unit has written a requirement that is off by a factor of one hundred for most currencies and correct for a few. Units, precision, time zones, and enumerations deserve their own column, every time. Payment programmes lose data the same way at every hop, which is the subject of the ISO 20022 truncation ledger, and the discipline of defining each field once is the data dictionary.

Step 3: How do you analyze an API’s behavior under failure?

By sending requests designed to fail, in the sandbox, and recording what really comes back. Documentation describes intent; failure paths are where intent and implementation part ways.

Work through these questions, and answer each with a request you sent:

• Synchronous or asynchronous? Does the response carry the final outcome, or a promise that one will arrive later by webhook, callback, or polling?
• What is the status model? A Stripe PaymentIntent moves through statuses including requires_payment_method, requires_confirmation, requires_action, processing, requires_capture, canceled, and succeeded. Which ones are final, and which can your process actually reach? A state machine of the statuses is a worthwhile artifact on its own.
• Is create safe to retry? Stripe accepts an Idempotency-Key header on POST requests, and its documentation says keys can be removed from the system after they are at least 24 hours old. So “safe to retry” has a time window, and your retry design must fit inside it. Idempotency testing shows how to prove it.
• What does an error look like? Send a declined test card such as pm_card_visa_chargeDeclined. Stripe returns HTTP 402 with an error object carrying type, code, decline_code, and message. Your customer messaging, reporting, and retry logic will all key off those fields, so capture a real one.
• How do webhooks behave? Stripe documents that it retries failed webhook deliveries for up to three days in live mode, that events are not guaranteed to arrive in order, and that each delivery is signed with a Stripe-Signature header. That means your consumer must tolerate duplicates, reorder, and verify signatures, which are three requirements the business never asked for and the integration cannot ship without. Specifying and testing those behaviors is covered in webhooks explained for analysts.

Here is the minimum failure set I send for any payment API, whatever the vendor:

Request	What it reveals
Valid request, twice, same idempotency key	Whether duplicates are prevented, and what the second response looks like
Same key, different payload	Whether the API detects misuse of a key
Missing required field	The shape of a validation error and whether the field is named
Invalid value, such as a bad currency	Whether enums are validated server side
Declined or rejected business case	The business error model, distinct from validation
Expired or wrong credential	401 versus 403, and whether errors leak information
Resource belonging to another account	Whether object-level authorization holds

Seven requests, an hour of work, and you know more about the API’s real behavior than most of the team will learn before testing starts. The design discipline behind choosing them is negative test design.

Step 4: How do you check limits and non-functional fit?

Take the API’s documented limits and do the arithmetic against your real volumes and timings. Limits only become meaningful when multiplied.

Rate limits. GitHub allows 60 unauthenticated requests per hour and 5,000 per hour for an authenticated user, and reports the remaining budget in X-RateLimit-Remaining. Stripe returns HTTP 429 when a client exceeds its limits. Ask: which calls count, per what (key, account, IP), and what the client must do on a 429.

Pagination. GitHub lists accept per_page up to 100 and describe further pages in the Link header. Stripe lists accept a limit of up to 100 and page with starting_after plus a has_more flag. Now do the sum:

A nightly reconciliation needs 30,000 records. At 100 per page that is 300 calls. At 60 calls per hour, that is five hours, so an unauthenticated design cannot finish inside a two-hour batch window. At 5,000 per hour it takes under four minutes.

That paragraph is a finding. It belongs in the worksheet, and it will change the design.

The rest of the non-functional list:

Check	Why it matters
Response time for the calls on your critical path	Your own timeout and customer experience budget
Payload size limits, file upload limits	Bulk operations, attachments, statements
Published status page and incident history	status.stripe.com and githubstatus.com exist for a reason; so does your run book
Test versus live differences	Stripe test cards never reach card networks, so live latency and decline patterns differ, and Stripe retries sandbox webhooks only three times over a few hours rather than for up to three days
Data residency and retention	Where customer data is stored and for how long
Support model and escalation path	Who you call during an incident, and how fast they answer

Write each as a measurable statement where you can. The format for doing that is in non-functional requirements.

Step 5: How do you assess versioning, change, and security?

Ask how the API changes over time and who controls when those changes reach you.

Versioning. Stripe uses date-named API versions: an account is pinned to a version, and a request can override it with the Stripe-Version header, so a breaking change reaches you only when you upgrade. GitHub’s REST API uses the X-GitHub-Api-Version header, with 2022-11-28 as a published version. An internal API with no versioning at all is a finding too, and usually the most important one in the worksheet. Assessing a breaking change when one arrives is covered in API versioning and breaking changes.

Questions to close out: Is there a public changelog? What counts as a breaking change? How much notice precedes a deprecation, and does the API signal it in responses? Who on our side watches for it?

Security and access. How are credentials scoped? GitHub fine-grained personal access tokens can be limited to specific repositories and permissions; Stripe restricted API keys can be limited to specific resources. Can you get a read-only credential for analysis? Who provisions test credentials, how long do they take, and is IP allowlisting required? Does any payload carry personal data that changes your logging or retention design?

Credential provisioning lead time deserves its own row. On bank programmes I have seen it be the longest single task in an integration, longer than the build.

What does an API analysis worksheet look like?

Copy this structure. One worksheet per API, one row per finding, and no row without evidence.

# API analysis: <API name and version>

Business need: <one sentence>
Environment analyzed: <sandbox URL> on <date>, API version <version>
Collection: <repo path or workspace link>

## 1. Capability
| Business step | Endpoint or event | Evidence (doc + request) | Fit | Decision |

## 2. Data
| Our field | Our format | API field | API format | Transformation | Risk |

## 3. Behavior
| Question | Observed answer | Evidence | Design impact |
- Sync or async, and how the final outcome arrives
- Status model and final statuses
- Idempotency mechanism and window
- Error model (validation vs business)
- Webhook retries, ordering, signatures

## 4. Limits and non-functional
| Limit | Documented value | Our volume | Arithmetic | Fit |

## 5. Change and security
| Topic | Finding | Risk | Owner |

## Gaps and decisions
| Gap | Option chosen | Rationale | Owner | Due |

How do you turn gaps into decisions?

Every gap gets exactly one of five decisions, and a named owner.

1. Transform on our side. Units, formats, and lengths, such as the amount conversion. Cheap, and it becomes a mapping requirement.
2. Change our process. The business accepts the API’s model, for example choosing from the three refund reasons.
3. Ask the provider. Feature requests to an external vendor rarely land within a project timeline; treat them as long shots. Internal providers are different, and a well-evidenced gap is the best argument you can bring them.
4. Accept and mitigate. Document the limitation, add monitoring, and put it in the run book.
5. Blocker. Stop, escalate, and evaluate an alternative.

The format for recording those decisions formally is fit-gap analysis. When a gap is uncertain rather than confirmed, do not argue about it in a meeting; timebox a spike and prove it, which is exactly what Part 7 on proofs of concept covers.

What mistakes do analysts make when analyzing an API?

• Trusting documentation without sending requests. Docs lag code. Every row needs a request.
• Analyzing only the happy path. The error model and the webhook behavior are where integrations fail.
• Listing endpoints and ignoring events. Half of most payment integrations is asynchronous.
• Forgetting units. Minor units, time zones, and enum casing cause more defects than missing endpoints.
• Skipping the limit arithmetic. A limit is not a finding until it is multiplied by your volume.
• Analyzing the sandbox as if it were live. Note every difference you know of, and flag what you cannot test.
• Leaving gaps without owners. A gap with no decision becomes a defect with a deadline.

The APIs for Analysts series

1. What is an API and how it works
2. Your first API collection in Bruno and Postman: requests, environments, variables, and secrets
3. How to analyze an API (you are here)
4. How to document an API: the sections consumers need, OpenAPI, and the error catalogue
5. How to write API test cases: deriving a complete suite from one endpoint
6. Chaining API requests with JavaScript: variables, scripts, polling, and a full Stripe flow
7. API proof of concept and demos: POCs and demos that settle decisions
8. The analyst who can send a request: why it is an edge, and a 30-day plan

Beyond the core series, the APIs for Analysts learning path organizes companion articles by level: the API glossary and troubleshooting failed requests for beginners, webhooks and GraphQL at intermediate level, and API design review, versioning and breaking changes, API security testing, and API tests in CI for advanced analysts.

The takeaway

API analysis evaluates an API against a real need through five lenses in order: capability, data, behavior, limits, and change. Map process steps to endpoints and events, map fields including units and formats, send failing requests to learn the true error and status model, multiply every limit by your volumes, and check who controls versions and credentials. Back every finding with a document and a request, give every gap a decision and an owner, and hand the collection to the build team as their starting point.

The worksheet structure above pairs well with the ready-made analysis and specification templates in Real-World BA Deliverables (20 Templates). If you are about to evaluate a vendor API and want a second pair of eyes on your worksheet before the steering committee sees it, book a 1:1 Tech BA Coaching Call, or browse everything at The Tech BA Toolkit.

Ahmed is a Senior Technical Business Analyst with 10+ years in banking and payments. He builds practical guides and tools for analysts at The Tech BA Toolkit.

Tags: API Analysis, Integration, Fit-Gap Analysis, Stripe, Systems Analysis