Business context explains why an API change or improvement matters by connecting the problem to organizational goals, departmental objectives, user goals, and relevant history. section 5.2.3 section 2.3
Provide business context by:
- Stating the change or improvement without assuming its cause or prescribing a solution. section 2.3
- Explaining the API user's goal and, where possible, showing the user journey. section 5.2.3
- Relating the problem to company or departmental goals, urgency, and relevant history. section 2.3
- Using an API profile, job story, digital capabilities, or value proposition canvas to make the API's role concrete. section 5.2.3
Product Catalog API
A review can frame the API as helping customers discover pet products through mobile, web, and affiliate channels. A job story identifies the situation, desired catalog exploration, and purchase-oriented outcome; search remains a later-phase capability. 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.
|
An API profile makes the business context scannable by listing the API's value proposition, consumers, job stories, access level, and planned capabilities. section 5.2.3
