Logistics API scenario walkthrough

When the customer is another team's code, "done" changes meaning. A screen can be fixed on Tuesday and nobody notices. A field that a partner has built against cannot be renamed on Tuesday without breaking something you cannot see. Logistics API is the scenario where the work product is a promise.

The project

Corridor Freight has a fixed budget of $70,000 and twelve weeks to launch a tracking and rate-quote API before its biggest partner goes live. There are four planned sprints. The partner is a commerce platform, and the date was promised in a contract.

The backlog is written for developers. Issue and revoke an API key. Sign every request and refuse a bad signature. Try the API in a sandbox that behaves like production. Limits and one error format for every response. Look up the current status of a shipment, read its scan history, list a partner's shipments with paging. Quote a rate by weight and destination, return the breakdown and its expiry, and refuse a bad request while saying why. And then the less glamorous items that decide whether anyone can use it: publish the reference from the OpenAPI description, a getting-started guide that reaches a first call, tests that fail when the documentation and the API disagree, and a changelog with a deprecation policy.

The last group is the unusual part. In this scenario, documentation and contract tests are in the backlog next to features, because for the people using the product they are the product.

What makes it advanced

The card names four outcomes: write user stories for developers instead of end users, treat documentation and contracts as part of "done", handle a breaking-change request without breaking a partner, and demonstrate real working calls, not mocked ones.

Stories with a different user. Our post on user story anatomy describes who, what and why. Here the "who" is a developer at a partner company, and the "why" is about integrating quickly and not being surprised later. Writing for that reader is a skill, and you see it tested.

A contract is a commitment. The lead architect will not publish a field he cannot support for years, and says early what a change costs the people who depend on it. A change that looks like a rename inside the team is a breaking change outside it. The scenario asks how you handle a request that sounds small and is not.

Honest demos. Showing mocked responses is easy and misleading. Showing real calls, including ones that fail, is the harder discipline. The sprint review is where it shows. See the Sprint Review is not a demo.

The people

The sponsor is the vice president of partnerships. She signed the contract with the anchor partner and promised the board the API would be ready. Her bonus and her reputation both ride on the date. She hears every request from the partner as an order and is quick to say yes, but she is not careless: shown on one page what a change would cost the partner, she backs the team.

The team, played by AI unless you take the role:

• The Product Owner manages partner integrations and is new to API products. She knows the partners well and the cost of an API change less well, so a request that sounds like a rename lands as a yes.
• The Scrum Master, when it is not you, keeps a list of every promise the team has made to a partner and reads it out when a request would break one.
• The lead architect designs and reviews the contract, and is slow to say yes to a rename and quick to say how to add instead.
• The developer-experience developer builds the portal, the reference and a sample client, and tests them by following the guide as if she were a partner.
• The backend developer joined from operations, knows how inconsistent the scan feeds and rate spreadsheets are, and will not build on a rule nobody has written down.

How the phases feel

Phase 1 moves from the business case and an integrator survey to the sprint length. In the epics workshop, partner expectations, the promised date and the team's view of risk meet.

The epics list that comes out includes the areas you might not expect on a feature list, such as the developer portal and webhooks, each with a value and a risk.

Phase 2 turns the top of the backlog into a sprint. You check the stories, run planning poker, break the work into tasks and freeze the sprint backlog. Documentation tasks sit beside the code tasks, and your estimates will show whether you counted them. From stories to tasks explains why testing and integration belong on the task list.

Phases 3 and 4 repeat for every sprint, with blockers, risks and mid-sprint requests, and a review where you decide what meets the Definition of Done. Here that includes documentation that matches the behaviour.

Phase 5 is the cutover, an agreement on the working deliverables, and a retrospective on the whole project. A scorecard follows, built from the decisions you recorded. It is a scorecard and not a certificate.

Questions to carry into it

Prompts worth keeping in mind as you play. None has a hidden answer.

• Who will build on this, and what do they need to trust it? A developer at the partner needs a stable contract, a sandbox that behaves like the real thing and documentation that is right.
• Can I add instead of change? Adding a field breaks nobody. Renaming one may break everyone, and the architect knows it.
• Is the documentation part of the sprint? If the answer is "later", the story is not done.
• Would this demo still work if the sandbox were switched off? A demo of real calls is a stronger piece of evidence than a polished mock.

The scenario is a technical one, and none of it requires you to write code. It requires you to think like the person on the other side of the interface.

Who it suits

The card says it is for learners comfortable with the ceremonies who want a technical product, and recommends Mobile Banking App first. The active work is estimated at about three and a half hours, spread over many days. You do not need to be an API developer to play it, but the vocabulary helps, and the scenario explains what it needs.

What each role takes from it:

• Scrum Master: protecting the team from requests that arrive as favours, and keeping the contract, the date and the timebox in one conversation.
• Product Owner: telling a senior partner contact that a simple-sounding change is not simple.
• Developer: saying early what a change costs the people who depend on it, and showing real calls.

The other scenarios are in the scenarios at a glance. Logistics API is fictional, as are Corridor Freight, the partner, its people and the figures. Nothing in it describes a real company.