RabbinatixDocs
Sign inGet started

Example

Build an order lookup flow

A customer opens one of their orders. The web app asks the orders service for it by id; the service reads it from its database and answers with the order, or with 404 when there is no such order.

You will build

  • 2 new systems: Orders Service and Orders DB
  • The GET /api/v1/orders/{id} API with a path parameter, and an orders.findById query
  • 2 pieces of logic: the order page and the lookup
  • The Order lookup flow with test data, 2 test cases and 1 requirement, all passing

System map

  • Web AppOrders ServiceGET /api/v1/orders/{id}
  • Orders ServiceOrders DBorders.findById (query)

This guide reuses Web App from the login example. Starting fresh? Create it first: Systems → New system, name Web App, kind Web frontend.

Part 1: Create the systems

  1. 1.

    Systems → New system, then Create system:

    Name
    Orders Service
    Type
    Backend service
  2. 2.

    And again:

    Name
    Orders DB
    Type
    Database

Part 2: Declare the order API

  1. 1.

    Open Orders Service. On APIs, click Add an API.

  2. 2.

    Under Basics:

    This endpoint is…
    Provided
    Method
    GET
    Path
    /api/v1/orders/{id}
    Summary
    One order by its id
    Lifecycle
    To do
  3. 3.

    Under Request, Path parameters shows {id}. Set its type to integer. A GET has no request body.

  4. 4.

    Type the 200 response’s body:

    id: integer
    status: string
    total: number
  5. 5.

    Click +404, type its body and click Create endpoint.

    error: string

Part 3: Connect the web app to the API

  1. 1.

    Open Web App → … → Add a dependency…. Consumer Web App, provider Orders Service.

  2. 2.

    Tick GET /api/v1/orders/{id} and click Connect 1 API.

Check: A green line joins Web App to Orders Service.

Part 4: Add the lookup

  1. 1.

    Open Orders DB → Resources → Operation. Keep may return nothing ticked, then Save.

    Name
    orders.findById
    Type
    query
    Query / description
    SELECT id, status, total FROM orders WHERE id = :id
    Input fields
    id: integer
    Output fields
    id: integer status: string total: number

Part 5: Build the lookup logic on the orders service

  1. 1.

    Open Orders Service → APIs. On GET /api/v1/orders/{id}, click + Logic. On Request has an id connection point: the path parameter.

  2. 2.

    Add Query Database (label Find order), Operation Orders DB · orders.findById (query). Connect the On Request arrow into it and id into its id connection point.

  3. 3.

    From Found: Return Response 200, with the query’s result connected straight into body (it has the same fields).

  4. 4.

    From Not found: Return Response 404. Body: Make Object error: string = Order not found.

  5. 5.

    Tick Key step on Find order.

Check: The Problems tab is empty.

Part 6: Build the order page logic on the web app

  1. 1.

    Open Web App → Logic → + Logic. Choose Event / UI action.

    Event name
    Open order page
    Name
    Open order page
  2. 2.

    Inputs:

    orderId
    Whole number
  3. 3.

    Return values:

    found
    Yes / No
    status
    Text
    message
    Text
  4. 4.

    Click Create and open. In Details, make status and message nullable (string | null).

  5. 5.

    Add Call Contract (label Load order) with API GET /api/v1/orders/{id}. Connect the On Event arrow into it and orderId into its id connection point.

  6. 6.

    From 200: Return with found = true, message = null, status from Get Property status on the call’s body.

  7. 7.

    From 404: Return with found = false, status = null, message from Get Property error on body.

  8. 8.

    From Other: Return with found = false, status = null, message = Something went wrong.

Check: The Problems tab is empty.

Part 7: Create the flow

  1. 1.

    Flows → New flow, then Create flow:

    Name
    Order lookup
    Where does the flow start?
    Existing logic
    (the list)
    Web App · Open order page (event)
    Criticality
    Normal

Check: Lanes Web App → Orders Service → Orders DB → Orders Service → Web App.

Part 8: Add test data

  1. 1.

    Test data → New test data → orders.findById. Name Placed order, WHEN id == 1001, THEN RETURN:

    { "id": 1001, "status": "placed", "total": 42.5 }
  2. 2.

    One more on orders.findById: No such order, WHEN id = * (any), THEN RETURN null.

  3. 3.

    Expected results → New expected result for Order lookup. Order shown: found equals true, status equals "placed".

  4. 4.

    Order missing: found equals false, message equals "Order not found".

Part 9: Write the test cases

  1. 1.

    Open Order lookup → Test → Manage… → New, once per row.

  2. 2.

    Existing order: expect Order shown.

    { "orderId": 1001 }
  3. 3.

    Missing order: expect Order missing. Pick No such order for orders.findById.

    { "orderId": 9999 }

Part 10: Link the requirement

  1. 1.

    Requirements → New requirement: An order that does not exist answers 404, not an error. Flow Order lookup, test case Missing order.

Part 11: Run it

  1. 1.

    Open the flow → Test → Run all.

  2. 2.

    Open a run and step through it: the Step data panel shows the id that went in and the order that came back.

Check: Both test cases are green.