RabbinatixDocs
Sign inGet started

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

Uses Shop App from the Online shop example and Orders Service from the Order lookup example. Any mobile app and backend service will do.

Part 1: Declare what the app expects

  1. 1.

    Open Shop App → Uses → Add a dependency. Provider: Orders Service.

  2. 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. 3.

    Fill in Basics:

    Method
    GET
    Path
    /api/v1/orders/{id}/tracking
    Summary
    Where the parcel is now
  4. 4.

    Set {id} to integer and type the 200 body the app needs:

    status: enum(packed, shipped, out_for_delivery, delivered)
    carrier: string
    eta: string(date-time) | null
  5. 5.

    Click Declare expectation.

Check: On the map, a grey dotted line joins Shop App to Orders Service: Unresolved. Nobody provides that API yet, and that is fine.

Part 2: Plan it on the provider side

  1. 1.

    Open Orders Service → APIs → Add an API. Provided, GET, /api/v1/orders/{id}/tracking, {id} as integer, the same 200 body, lifecycle To do.

  2. 2.

    Turn on Also create an API request. Requested by: Shop App. Pick a Needed by (optional) date two weeks out.

  3. 3.

    Click Create endpoint.

Check: The line turns into a blue dashed Planned line, and the board has an API request ticket for the orders team.

Part 3: Give the app team a test server

  1. 1.

    Open Orders Service → Test server. Click the tracking API in the list.

  2. 2.

    Click Copy URL. The app team calls that address plus /api/v1/orders/1001/tracking and 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. 1.

    When the orders team has built it, open the endpoint on Orders Service → APIs, press Edit, set Lifecycle to Deployed and click Save changes.

  2. 2.

    Open Board: the API request ticket moved with the endpoint’s lifecycle.

Check: The line from Shop App to Orders Service is green: Healthy.