API requirements & integration design — the analyst's craft.
Business need
? ? ?
Buildable requirements
Marko Hartikainen→ / space to advance · N notes · F fullscreen
Today's villain · a real shape of pain
Four hours. Six percent typos. Zero visibility.
Repair shops — the workshops and dealerships reporting damage on the customer's behalf — send it by e-mail; someone re-types it into the core claims system.
Median 4 hours from report to registration · ~6% of claims carry re-typing errors · the shops phone in to ask for status.
The target: registered within a minute, status visible in the repair-shop portal automatically.
this case carries the whole session — every block moves it forward
From part 1 · the promise we made
The questions you ask in week one decide whether the integration hurts in month six.
Today is week one.
Recap · part 1 in one slide
You have a map and five questions
request / response
RESTGraphQLgRPCSOAP*
push
webhooksWebSockets
messaging
queuespub/subevent streams
bulk
files · SFTPEDI*ETL / ELT
infrastructure
API gatewayiPaaSESB*
five routing questions: answer-to-proceed? · data or process? · volume & bursts? · other side down? · who controls both ends?
Your homework · the API you brought in your head
Where did your API land on the map?
Two or three volunteers: name the API, its family, sync or async, how timely.
Then the valuable part: the question about it you couldn't answer.
Drop yours in the chat — several of them get answered live today; the rest go to the parking lot.
the question you can't answer is exactly what a requirements checklist is for
The series · you are here
Part 2: analyse & specify
1 · done ✓
Understand & choose
The landscape, the framework, when not to build an API.
2 · today
Analyse & specify
Discovery → requirements → design contribution → roles. Plus your first live API calls.
3 · TBA
Secure
REST security layer by layer — you spot the weaknesses.
4 · TBA
Operate & work smarter
Documentation, testing, lifecycle, risks, LLMs.
plan for today: discovery → functional requirements → the contract, live → break → NFRs → diagrams & mapping → roles → gap-hunt · one 6-minute break at about :46
Concept · where analysis sits
Four steps, and today is 1 → 3
1 · Discovery
2 · Options with the architect
3 · Requirements + data mapping
4 · Build & test support
Discovery — establish facts before anyone names a technology.
Options — you bring the business facts, the architect brings the patterns; the choice gets recorded with its rationale.
Requirements — the facts become testable statements: functional, non-functional, and a field-level data mapping.
The case · what the business actually handed us
The brief, and the systems behind it
Repair-shop portal vendor-hosted
FNOL
Core claims system Claims API v1.2 · source of truth
enrich
Vehicle registry REST v2 · 100 req/min
+ a reinsurer receiving a nightly bordereaux file over SFTP — the bulk family never left
The brief says: "register claims via API within a minute, show status in the portal."
The brief does not say: volumes, peaks, failure behaviour, duplicate rules, who owns what.
Concept · the discovery question set
Seven groups of questions, one page of answers
Business context
What process needs this — and what breaks if we don't build it?
Systems & ownership
Source, target, and who owns each side — technically and organisationally.
Data
Which entities and fields, source of truth, quality, personal-data classification.
Timing & volume
Freshness needed, who initiates, daily and peak volumes, growth.
Failure tolerance
What may fail silently vs must alert; is there a manual fallback?
Security & compliance
Access, legal basis for personal data, retention, audit needs.
Constraints
Partner capability, existing interfaces, deadlines, budget reality — vendor lead times bite here. Ask the API's version & deprecation policy now (full treatment in session 4).
The template
A discovery questionnaire — one page, seven sections, an open-questions log.
Pro-tip · the discipline that makes discovery work
Resist solutioning
"REST API" is not an answer to "how fresh must the data be?"
Discovery collects facts in business units: minutes, counts, euros, names of owners.
Technology re-enters at option shaping — with the architect, against the facts.
"We don't know yet" is a valid answer — written in the open-questions log with an owner. An unwritten unknown returns as a month-six incident.
Your turn · chat waterfall · 2 minutes
Your first question to this brief?
Type it in the chat — don't send. Everyone presses Enter on "3-2-1".
Onsite: shout it out when the waterfall lands.
Reveal · what discovery unearthed here
None of this was in the brief
~150 reports/day sustained — but 800/day during one storm week. Peak, not average, sizes the design.
The reporter waits for the claim number → intake is synchronous. Status updates? ≤ 5 minutes is fine → events, not polling.
Intake must not fail when the vehicle registry is down.
Duplicates are unacceptable — a claim registered twice is paid twice.
The repair-shop portal's vendor supports REST and webhooks — no message-broker client. Constraint beats preference (question 5!).
Concept · what a functional requirement is made of
FR anatomy: five parts, every time
Trigger — what starts it (a user action, an event, a schedule).
Operation — which API operation, referencing the spec by name.
Rule — the validations and business rules that apply.
Outcome — what happens on success, including what the user sees.
Unhappy path — what happens when it fails. The part that's usually missing.
a requirement missing its unhappy path is half a requirement
Spot the error · 60 seconds — what's wrong with this FR?
requirement · draft
FR-X: The system prevents duplicate claims.
Take a moment. Which of the five parts are present?
Who is "the system"? What does "prevents" look like at runtime? How would a tester verify it?
Before → after · the same intention, buildable
The improved version
requirement · FR-2 · duplicate protection
Trigger: a repair shop submits an FNOL from the portal
Operation: POST /claims (Claims API v1.2) with an Idempotency-Key
header, one key per FNOL, reused on retry
Rule: resubmission with the same key SHALL NOT create a
second claim; same vehicle+incident with a different
key → 409 DUPLICATE_CLAIM
Outcome: the portal shows the returned claimId
Unhappy: on timeout the portal retries with the SAME key —
no duplicate is possible by construction
The spine question
Ask every arrow: "what happens when it fails?"
Every answer is a requirement. Silence here is where incidents are born.
The question, applied · the registry is down. now what?
The fallback branch is a business decision
Intake
enrich · 3 s timeout
Vehicle registry
no answer?
register anyway flag ENRICHMENT_PENDING
FR-5: no registry answer within 3 s (or any error) → register without enrichment, flag ENRICHMENT_PENDING, retry up to 24 h, then a worklist item for a human.
Who chose 3 seconds, 24 hours, and "register anyway"? The business did — the analyst asked.
Documentation · the same contract, three outfits
One operation, three views
raw · OpenAPI YAML
The source
Machine-readable contract: paths, schemas, required fields, error responses. What tools — and AI assistants — read.
rendered · Swagger UI
The browsable version
The same file, rendered: expandable operations, examples, and a Try it out button. Where analysts usually live.
written · wiki page
The context layer
What YAML can't say: ownership, business rules in prose, support contacts, runbook links. Your team's wiki does this job.
all three describe POST /policies of the demo API — full documentation treatment in session 4
Demo · hands-on — everyone
Watch for: 200 → padlock → 401
Open api.cybernotes.it/mtpl/docs — the demo API's Swagger UI.
First call succeeds for everyone. The second one won't. Predict why before you press it.
Everything to follow along — base URL, credentials, a paste-ready cURL sheet, and the Postman/Bruno collection — is on one page: api.cybernotes.it/mtpl/start. Pick the client path that fits your machine.
Demo · call №1 — everyone gets a 200
Your first live call
In Swagger UI: GET /coverage-options → Try it out → Execute.
Read it like part 1 taught: verb · path · status · body.
Postman: GET api.cybernotes.it/mtpl/v1/coverage-options
every registration traceable by traceId + source + timestamp · kept 7 years
p95 = the time 95% of calls beat — one slow call in twenty may be slower
Your turn · rewrite drill · 2 minutes
Rewrite: "status updates must be reliable."
Make it a number with a unit and a condition — for this case.
Hint: reliable against what — loss? delay? disorder? Pick, then quantify.
Concept · observability as requirements
Write down who notices
Alerting: error rate > 2% over 5 minutes → claims-ops on-call · event silence > 15 minutes in business hours → same. Named conditions, named receivers.
Correlation: every registration traceable end-to-end by a traceId — the thread support pulls when something breaks at 02:00.
Audit: who registered what, from which source, when — retained 7 years. In a bank, this is a requirement, not a nice-to-have.
The division of labour
Numbers come from the business. Feasibility comes from the architects.
Your job is to ask until the adjective becomes a number.
Concept · the two diagrams that carry everything
Context + sequence — with the else branches
Context diagram — one box per system, one arrow per flow: who talks to whom about what. Slide 8 was one.
Sequence diagram — one scenario over time, including what happens on timeout, rejection, retry.
Informal is fine. Complete is mandatory — the happy path alone is a brochure, not a design.
If you can't draw the else branch, you've found your open question. The diagram is a discovery tool wearing a deliverable's clothes.
Concept · data mapping — two true detective stories
Mapping finds what nobody asked
gap 1 · the enum with no home
Registry says fuel_type: gas. The core system has no such value. A bulk "lowercase→UPPERCASE" rule would map it wrong, silently. Value-by-value mapping catches it → decision needed, owner: product. Don't guess.
gap 2 · the field that became a requirement
Registry carries status: stolen — the core system has nowhere to put it. Ask "do we care?" → claims handlers very much do for THEFT claims → a brand-new FR routes them to manual review. A bulk mapping would have dropped it — and the requirement with it.
also: null ≠ absent ≠ empty string — known-empty · not-supplied · supplied-but-blank are three different facts · full method in the try-at-home exercise
Concept · working with the solution architect
You bring · they bring
you bring (business facts)
the architect brings
freshness needed · volumes, peaks, growth
integration type & pattern
failure tolerance · manual fallback reality
middleware, technology, reuse
data ownership & classification
security mechanics
cost of delay — what an hour of downtime costs
effort, feasibility, platform fit
architect-side vocabulary you'll hear: orchestration (one coordinator drives the steps) vs choreography (each service reacts to events, no central conductor) — recognize the words, let them own the choice
expect 2–3 options back · the choice is recorded with its rationale — an unrecorded decision gets re-litigated
Concept · who, and when — the map
Contact · consult · inform
contact — work with directly
Business Owner · Product Owner · System Owner (each end!) · Data Owner · Developer/Tech Lead · Vendor contact · the counterpart's analyst
consult — at decision points
Solution / Integration / Enterprise Architect · Security Architect · IAM · DPO · Compliance/Risk · Network · API Platform Owner · QA Lead
inform — they inherit it
Operations/Support · Monitoring Owner · Release Manager — before build ends, not after go-live
the full one-pager with entry moments carries all twenty roles
Pro-tip · the three misses that cost weeks
The expensive late arrivals
The vendor's technical contact — sandbox access, credentials, onboarding: ask in week one; these lead times routinely beat the build time.
The DPO — the legal-basis question for personal data. You ask it; they answer it. Asking late can reshape the payload design.
The second System Owner — every integration has two ends. The far end's owner learns about the project surprisingly late, surprisingly often.
the cheapest meeting is the one in week one
Exercise · pairs · ~7 minutes hunting
Gap-hunt: a draft spec landed on your desk
A vendor sends the v0 draft of the policy API you're about to integrate with. Something's off. Several things, actually.
Pairs — mix business + system analysts, room + remote. Hunt with today's checklist: discovery groups, FR anatomy, NFR numbers.
Score: one point per gap phrased as a question to the API owner. Complaints score zero.
spec: api.cybernotes.it/mtpl/v0/openapi.yaml · key excerpt on the next slide · six gaps are planted — find five and you're dangerous
Exercise · the suspect — key excerpt
mtpl-openapi-v0.yaml · excerpt 1
paths:
/coverage-options: get → 200
/auth/token: post → 200
/policies: post → 201 · get → 200
/policies/{id}: get → 200, 404 · put → 200
/policies/{id}/cancel: post → 200components: (no securitySchemes)
excerpt 2 · the request schema
PolicyRequest:
required: [vehicleId, holderName]
properties:
vehicleId:
type: string
example: "WVWZZZ1JZXW000001"
holderName:
type: string
POST /policies example body:
vehicleId: "ABC-123"# ...wait.
hunt with the checklist: capability? data clarity? errors? security? volumes? — one question per gap
Reveal · the six planted gaps
#
gap
the question it becomes
1
no auth documented (yet a token endpoint exists)
how do callers authenticate — and which operations need what?
2
error responses missing almost everywhere
what does a rejection look like — codes, format?
3
vehicleId: reg number and VIN mixed in examples
which identifier, which format, validated how?
4
one-active-policy rule invisible
what happens on the second sign-up — 409? merge? silence?
5
no pagination on GET /policies
what happens at 60+ policies — and what's the page limit?
6
no rate-limit information
what are the limits, and what do we do on 429?
the live v1 in Swagger UI documents all six — that's the before/after of today's whole craft
Before you go · the checklist grows, the padlock waits
Today moves to your checklist — the 401 waits for part 3
right now
Your checklist grows
Discovery groups, FR anatomy, NFR numbers, mapping method, SA handover, the roles map — plus your top-3 gaps from the hunt.
link → on the training page
try at home · pick one
Aim it at your API
1 · Run the discovery questionnaire + checklist against your homework API — especially the question you couldn't answer. 2 · Repeat today's two calls yourself — everything you need is the one-page api.cybernotes.it/mtpl/start (Postman collection linked there). 3 · Full mapping exercise with the sample specs.
for part 3
The padlock
We left POST /policies answering 401. Part 3 opens it: tokens, scopes, and every control between a caller and a bank's data.
slides → cybernotes.it/trainings/api-integration/2-requirements-and-design · PDF on the same page · part 3: in preparation
Appendix · the requirements pack — reference, not memory work
What a complete pack contains
1
Overview & context diagram — who talks to whom, one page
2
Parties & environments — owners both ends, sandbox/prod, test-data rules