A job story is an enhanced user story shaped by Jobs to Be Done thinking. It describes the situation that triggers a need, the user’s motivation or goal, and the outcome they expect. For API design, it makes the consumer’s intended task explicit and provides business context for review. section 5.2.3
Build the statement around three questions:
- When does the user need the API? section 5.2.3
- What motivation or goal is the user trying to fulfill? section 5.2.3
- What outcome should the API enable? section 5.2.3
Product Catalog API
When I need a product to care for my pet, I want to discover a broad range of products in that category with quality reviews so I can choose which one I like. This context helps the API team identify the high-level tasks and digital capabilities the API must support. section 5.2.3
Table 5.1 Example of an API profile
|
Item
|
Description
|
|---|---|
|
API name
|
Product Catalog API
|
|
API value proposition
|
An API to discover Acme’s great range of products so users can find products to care for their pets
|
|
API consumer
|
The end user is a customer browsing Acme Pet Supplies products to make a purchase. Client API developers will use this API to build three end-user channels: the Acme mobile app, the Acme web store, and an affiliate’s store.
|
|
Job stories
|
Story 1:
When exploring what products Acme has available, I want to browse the Acme catalog by category so I can find new and exciting pet products that interest me.
Story 2:
When exploring what products Acme has available, I want to search for particular pet products in the Acme catalog so I can view details of the product and decide if I want to buy.
Note: Search catalog capability will be in phase 2.
|
|
Access level
|
Public API, made available for use by both Acme-owned digital channels and registered affiliates
|
|
Usage plans
|
Acme mobile app: 10 requests a minute
Acme web store: 10 requests a minute
Affiliate stores: 8 requests a minute
|
|
Security model
|
API requests should be authorized using OAuth2. We’ll start with the read permission scope for the MVP but will add more scopes as the API functionality is expanded.
|
Compare catalog job stories with the API’s value proposition, consumers, access level, and phased capabilities. section 5.2.3
