Example
Ask for an API that doesn’t exist yet
The mobile app needs to show where a parcel is, but the orders service has no such API. The app team declares what it expects; the map shows it as unresolved, the orders team gets a request, plans it, gives it a test server for the app team and finally releases it.
You will build
- An expectation from Shop App that turns from Unresolved to Planned to Healthy
- An API request ticket on the board for the orders team
- A test server URL the app team can build against today
System map
- Shop AppOrders ServiceGET /api/v1/orders/{id}/tracking
Part 1: Declare what the app expects
- 1.
Open Shop App → Uses → Add a dependency. Provider: Orders Service. - 2.
Click Need an API that doesn't exist yet?. The endpoint editor opens with Consumed (expectation) picked and Calls system set to Orders Service. - 3.
Fill in Basics: - Method
- GET
- Path
- /api/v1/orders/{id}/tracking
- Summary
- Where the parcel is now
- 4.
Set {id}tointegerand type the 200 body the app needs:status: enum(packed, shipped, out_for_delivery, delivered) carrier: string eta: string(date-time) | null
- 5.
Click Declare expectation.
Check:
Part 2: Plan it on the provider side
- 1.
Open Orders Service → APIs → Add an API. Provided, GET,/api/v1/orders/{id}/tracking,{id}asinteger, the same 200 body, lifecycleTo do. - 2.
Turn on Also create an API request. Requested by: Shop App. Pick a Needed by (optional) date two weeks out. - 3.
Click Create endpoint.
Check:
Part 3: Give the app team a test server
- 1.
Open Orders Service → Test server. Click the tracking API in the list. - 2.
Click Copy URL. The app team calls that address plus /api/v1/orders/1001/trackingand gets an answer shaped like the contract.Type a Sample key (optional) to get other example values. The same key always answers the same.
Part 4: Release it
- 1.
When the orders team has built it, open the endpoint on Orders Service → APIs, press Edit, set Lifecycle to Deployedand click Save changes. - 2.
Open Board: the API request ticket moved with the endpoint’s lifecycle.
Check:
