Pepelen
← Systems Analysis: APIs, Integrations and Data

Lesson

End-to-end case: from a user story to an integration specification

From a Romashka user story, put together a mini-specification — system requirements, a measurable NFR, an endpoint contract, an event, a call sequence, the affected statuses and an SQL check — and self-check it against the course checklist.

1 / 7

Putting it all together

A specification is a consistent set

The real job of a systems analyst is not a single diagram but a consistent set, where no part contradicts another. Example: cancelling an order, from the first lesson of the course: • the state diagram has no transition from in_delivery to cancelled; • the requirement says: “in the in_delivery and delivered statuses, the order service refuses cancellation”; • the contract of POST /v1/orders/{orderId}/cancel has a 409 response with currentStatus; • the SQL check: cancelled orders that the courier had already picked up (picked_up_at IS NOT NULL) — 0 rows. Different refusals, different codes: the current status is in the way — 409; the data breaks a rule (an address outside the delivery zone) — 422; the resource doesn't exist — 404. There is one error format for the whole API — Problem Details. The order of work on a specification is in the steps below. Before handing it in, check yourself against the course checklist of common mistakes: • only success is described, no failures; • “fast” instead of a percentile, a threshold and a load; • a verb in the path (/changeAddress) instead of an HTTP method; • the contract has only 200, and the error goes in the body; • “the broker will deliver exactly once”, and nobody discards duplicates; • a command event (ChangeAddress) instead of a fact; • a list of values in one table cell; • “= NULL” instead of IS NULL.
From a user story to a specification
  1. 1
    System requirements

    Component, action, data, condition and failure

  2. 2
    NFR

    Metric, threshold and load

  3. 3
    Contract

    Method, path, body, all codes, error format, idempotency

  4. 4
    Integrations

    What is synchronous and what is an event; an event is a fact with an eventId and a message key

  5. 5
    Sequence

    “Who → whom: what” steps with a failure branch

  6. 6
    Statuses

    In which statuses the action is allowed and what we respond in the others

  7. 7
    Data and check

    Fields and tables; an SQL query that looks for violations

Lesson notes
A specification is a consistent set
The real job of a systems analyst is not a single diagram but a consistent set, where no part contradicts another. Example: cancelling an order, from the first lesson of the course: • the state diagram has no transition from in_delivery to cancelled; • the requirement says: “in the in_delivery and delivered statuses, the order service refuses cancellation”; • the contract of POST /v1/orders/{orderId}/cancel has a 409 response with currentStatus; • the SQL check: cancelled orders that the courier had already picked up (picked_up_at IS NOT NULL) — 0 rows. Different refusals, different codes: the current status is in the way — 409; the data breaks a rule (an address outside the delivery zone) — 422; the resource doesn't exist — 404. There is one error format for the whole API — Problem Details. The order of work on a specification is in the steps below. Before handing it in, check yourself against the course checklist of common mistakes: • only success is described, no failures; • “fast” instead of a percentile, a threshold and a load; • a verb in the path (/changeAddress) instead of an HTTP method; • the contract has only 200, and the error goes in the body; • “the broker will deliver exactly once”, and nobody discards duplicates; • a command event (ChangeAddress) instead of a fact; • a list of values in one table cell; • “= NULL” instead of IS NULL.