Writing API Use Cases Around Real User Goals
An API endpoint is easy to describe from a technical angle: it accepts a request, applies rules and returns a response. That description is useful for developers, but it does not explain why the endpoint exists or how it supports someone completing a task. A user-centred use case connects the endpoint to a real goal, such as booking a medical appointment, checking a parcel or updating a delivery address.
Writing use cases for API endpoints from a user perspective helps product, design, engineering and testing teams share the same understanding. In UCDmanager, these scenarios can sit alongside personas, requirements, usability findings and accessibility evaluations, giving the API a clear place in the broader user-centred design process.
Start with the user goal
Begin with the outcome a person wants, rather than the route, method or database operation. “A customer wants to see when their parcel will arrive” is a stronger starting point than “The client calls GET /shipments/{id}”. The first statement gives the team a reason to examine the endpoint; the second gives only an implementation detail.
A useful use case identifies the primary actor, their goal, the context and the value of success. For an Australian retail service, the actor might be a customer in Melbourne checking a delivery before leaving work. The same endpoint may serve a warehouse operator, but that person needs a different scenario, permission set and level of detail.
Describe the journey around the endpoint
An endpoint is usually one step in a wider interaction. Write what happens before the request, what the user expects afterwards and how the result changes their next action. For example, a resident uses a council mobile app to report a damaged footpath, receives a confirmation, and later checks whether the issue has been assigned to a maintenance team.
The use case can mention the API operation inside the flow without making it the headline. “The service retrieves the report status” is meaningful when connected to “the resident wants reassurance that the council has received the report”. This framing prevents teams from treating a successful HTTP response as the same thing as a successful user experience.
Give each actor a clear role
Actors may be end users, support staff, administrators, partner systems or automated services. Define what each actor is allowed to do and what information they need. A customer may view an order, while a contact-centre employee can correct an address after verifying identity. The API should reflect those distinctions through authorisation, data filtering and appropriate error responses.
A practical way to clarify responsibilities is to document user roles alongside the use cases. This is especially important for services used across Australian organisations, where a MyGov-style account holder, a government case worker and an external service provider may interact with the same platform under different privacy obligations.
Make the main flow observable
Write the happy path as a sequence of visible user outcomes, not a list of internal functions. A scenario might say that the customer signs in, selects an order, requests tracking information, sees the latest scan event and receives a plain-language delivery estimate. Each step can then be mapped to a request, response, interface state or business rule.
Include enough detail for designers and testers to recognise whether the flow works. If the endpoint returns an empty shipment history, the interface should explain that tracking has not started rather than display a blank panel. If a regional customer has intermittent NBN or mobile coverage, the application may need cached information and a clear indication of when data was last updated.
Cover exceptions, privacy and accessibility
Alternative flows often reveal the most important requirements. Document expired tokens, missing records, duplicate submissions, rate limits, validation failures and temporary outages. Explain the user consequence and the recovery path: can the person retry, edit the information, save progress or contact support?
Privacy and accessibility belong in the use case rather than being added at the end. A request for a Medicare-related service should expose only necessary personal information, while an accessible error must be available to screen readers, use understandable language and identify the field requiring attention. Australian teams should also consider the Privacy Act, state service expectations and WCAG conformance when defining API-backed experiences.
Connect research to endpoint behaviour
Use cases should be grounded in evidence from interviews, support records, analytics and usability tests. If research shows that customers frequently submit a form twice because the confirmation is slow, the scenario should describe duplicate prevention, progress feedback and a safe retry strategy. This turns a vague complaint into testable product and API requirements.
When several research findings compete, affinity mapping can reveal recurring needs and patterns; affinity diagrams for research can help teams group evidence before deciding which endpoint behaviours matter most. For instance, feedback from Sydney commuters, regional customers and call-centre staff may point to different priorities around speed, offline access and status visibility.
Keep technical detail useful
Technical information belongs in the use case when it affects the user outcome. Record authentication requirements, expected status codes, data freshness, pagination, idempotency and dependencies where they influence the journey. Avoid filling the scenario with implementation choices that may change during delivery.
A scraper that collects publicly available information, for example, still needs a user-centred purpose such as helping a researcher compare product availability. The team can consult guidance on implementing a web scraper for engineering considerations, while the use case explains consent, source reliability, update frequency and what the person should see when a source is unavailable.
Maintain scenarios as living artefacts
API contracts, interface designs and user needs evolve together. Store the use case with its acceptance criteria, related persona, endpoint reference and test evidence, then review it whenever the service changes. A new authentication policy or response field can alter the user journey even when the endpoint name stays the same.
Version control makes those changes traceable. Teams documenting UX decisions can benefit from version control in UX, particularly when a distributed team in Brisbane, Perth and Adelaide is refining the same service. In UCDmanager, linking scenarios to research and evaluation records helps preserve why a behaviour was chosen, not just what the current API happens to do.