Part 2
Before build starts
API requirements and integration design — the analyst's half of the work
The slides open in your browser and work with the keyboard: arrow keys to move, N for speaker notes.
Turning a business brief into an integration specification: the questions worth asking in week one, functional requirements with their error branches, non-functional requirements expressed as numbers, data mapping, and the roles map. Includes live calls against a synthetic insurance API and a gap-hunt on a deliberately flawed OpenAPI spec.
What you will be able to do
- Interrogate a business brief without solutioning, using seven groups of questions
- Write a functional requirement with all five parts, including the error path
- Turn vague quality statements into non-functional requirements with numbers in them
- Read an OpenAPI specification well enough to notice what is missing
- Work out which roles to contact, consult or inform — and when
- Make your first authenticated API calls, and read the errors deliberately
Prerequisites
Part 1, or equivalent familiarity with integration styles. For the hands-on section you need a browser — the demo API’s documentation page runs requests directly, so there is nothing to install. A terminal or an API client works too if you prefer one.
Four hours of manual work a day. Six percent of records carrying a typo. No visibility into whether anything arrived. That is a real integration failure pattern, and none of it was caused by bad code. It came from requirements that described the happy path and stopped there.
The questions asked in week one tend to decide whether an integration hurts in month six. This session is about those questions.
What you should be able to do afterwards
Take a short business brief and produce something a developer can build from and a tester can verify against — including the parts nobody wrote down, which are usually the interesting ones.
Concretely: moving from “the system must reliably send status updates” to a requirement with numbers, actors, triggers, error branches and acknowledgements in it.
The ground it covers
Asking without solutioning. Seven groups of questions covering the business process, the systems involved, triggers, data ownership, volume, latency, and the third-party constraints that tend to arrive late — partner sandbox availability, onboarding lead times, rate limits, SLAs. The discipline is holding off on a solution while you are still establishing the problem, which is harder when you already have one in mind.
Functional requirements that survive contact. A functional requirement has five parts; drafts often have two. The session works a weak requirement into a better one on screen, then does the same for error handling. For every arrow on the diagram: what happens when it fails? The fallback branch is a business decision rather than a technical one, and if it is not made deliberately it gets made at 3am by whoever is on call.
Non-functional requirements as numbers. “Fast”, “reliable” and “auditable” are adjectives rather than requirements. This covers performance, availability, auditability, supportability, compatibility, idempotency, retries and correlation IDs — and where the numbers come from, which is the business for the target and the architects for whether it is achievable.
Reading a specification critically. One operation seen three ways: the human description, the OpenAPI definition, and the live response. Where they disagree, at least one is wrong, and there are questions that expose which.
Data mapping. In my experience this is the exercise that surfaces requirements nobody asked for — fields with no source, values with no agreed meaning, and two systems that both believe they own the customer record.
The roles map. Twenty roles, and for each one whether you contact, consult or inform, and roughly when. Security, data protection and operations are expensive to involve late, mostly because by then the decisions they care about are already fixed.
The hands-on part
This session uses a live demo API built for the series: a fully synthetic mandatory motor insurance register. Credentials take a few seconds to get from the site — no account, no email address — and then the calls are real.
The sequence is deliberate. An open endpoint returns 200. A protected one returns 401, and it is worth reading properly, because that is where Part 3 starts. Then you authenticate, insure a vehicle, and try to insure it again to meet a 409 that exists to make a point about business rules living inside an API.
It closes with a gap-hunt. A draft OpenAPI specification lands on your desk, deliberately flawed: no auth section, most operations missing error responses, one ambiguous identifier, an absent business rule, and no mention of pagination or rate limits. The job is to find what is not there. Specifications arriving in real work are often incomplete in similar ways, and usually nobody has marked them up for you.
Where this session stops
It covers requirements practice for integrations specifically. It does not cover requirements engineering as a discipline, data modelling, or process modelling in BPMN — all adjacent, all worth their own time.
If you want to go further:
- The OpenAPI Specification itself — spec.openapis.org is readable, and reading it once changes how you review API documentation.
- Error responses — RFC 9457, Problem Details for HTTP APIs is short, and gives you a standard to point at rather than an opinion.
- Event-driven interfaces — AsyncAPI is the equivalent for messaging, and the gap in most analysts’ toolkit, mine included until recently.
- Requirements practice generally — BABOK, or the BCS business analysis material if you are in Europe. Neither is integration-specific, and both are better than this session on fundamentals.
Next
Part 3 goes back to that 401 and takes the security layer seriously.