RabbinatixDocs
Sign inGet started

Example

Build an add-to-cart flow

A shopper adds a product to the cart. The cart service accepts 1 to 10 of a product, checks that the product exists and saves the cart line. Too many, too few or an unknown product each get a clear answer.

You will build

  • 2 new systems: Cart Service and Shop DB
  • The POST /api/v1/cart/items API and 2 database operations
  • 2 pieces of logic: the Add to cart button and the cart logic
  • The Add to cart flow with test data, 4 test cases and 1 requirement, all passing

System map

  • Web AppCart ServicePOST /api/v1/cart/items
  • Cart ServiceShop DBproducts.findById (query)
  • Cart ServiceShop DBcart_items.insert (insert)

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
    Cart Service
    Type
    Backend service
  2. 2.

    And again:

    Name
    Shop DB
    Type
    Database

Part 2: Declare the cart API

  1. 1.

    Open Cart Service → APIs → Add an API.

  2. 2.

    Under Basics:

    This endpoint is…
    Provided
    Method
    POST
    Path
    /api/v1/cart/items
    Summary
    Add a product to the cart
    Lifecycle
    To do
  3. 3.

    Type the Request body:

    productId: integer
    quantity: integer
  4. 4.

    Change the 200 response’s status to 201 and type its body:

    itemId: integer
    quantity: integer
  5. 5.

    Click +400 and +404, give both the body below, then 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 Cart Service.

  2. 2.

    Tick POST /api/v1/cart/items and click Connect 1 API.

Part 4: Add the database operations

  1. 1.

    Open Shop DB → Resources → Operation. Keep may return nothing ticked and Save.

    Name
    products.findById
    Type
    query
    Query / description
    SELECT id, name, price FROM products WHERE id = :productId
    Input fields
    productId: integer
    Output fields
    id: integer name: string price: number
  2. 2.

    Operation again. Untick may return nothing and Save.

    Name
    cart_items.insert
    Type
    insert
    Query / description
    INSERT INTO cart_items (product_id, quantity) VALUES (:productId, :quantity)
    Input fields
    productId: integer quantity: integer
    Output fields
    id: integer

Part 5: Build the cart logic on the cart service

  1. 1.

    Open Cart Service → APIs. On POST /api/v1/cart/items, click + Logic.

  2. 2.

    Add Break Object with these fields, fed from On Request body:

    productId: integer
    quantity: integer
  3. 3.

    Add Validate Range on quantity. In Details: Field name quantity, Min 1, Max 10. Then a Branch Quantity allowed? on its valid.

  4. 4.

    From False: Return Response 400, body Make Object error: string from the validation message.

  5. 5.

    From True: Query Database products.findById (label Find product), productId from Break Object.

  6. 6.

    From Not found: Return Response 404, body Make Object error = Product not found.

  7. 7.

    From Found: Database Insert (label Save cart line), Operation cart_items.insert, with productId and quantity from Break Object.

  8. 8.

    Then Return Response 201. Body: Make Object itemId: integer + quantity: integer, with itemId from Get Property id on the insert result and quantity from Break Object.

  9. 9.

    Tick Key step on Find product, Save cart line and the 201 answer.

Check: The Problems tab is empty.

Part 6: Build the button logic on the web app

  1. 1.

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

    Event name
    Press Add to cart
    Name
    Press Add to cart
  2. 2.

    Inputs:

    productId
    Whole number
    quantity
    Whole number
  3. 3.

    Return values:

    success
    Yes / No
    message
    Text
  4. 4.

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

  5. 5.

    Add Make Object (label Build request) with these fields, connected from On Event:

    productId: integer
    quantity: integer
  6. 6.

    Add Call Contract (label Add item) with API POST /api/v1/cart/items. Connect the On Event arrow into it and object into body.

  7. 7.

    From 201: Return with success = true and message = null.

  8. 8.

    From 400 and from 404: a Return each, success = false, message from Get Property error on body.

  9. 9.

    From Other: Return with success = false and message = Something went wrong.

Check: The Problems tab is empty.

Part 7: Create the flow

  1. 1.

    Flows → New flow, then Create flow:

    Name
    Add to cart
    Where does the flow start?
    Existing logic
    (the list)
    Web App · Press Add to cart (event)
    Criticality
    Important

Check: Lanes Web App → Cart Service → Shop DB → Cart Service → Web App.

Part 8: Add test data

  1. 1.

    Test data → New test data → products.findById. Coffee mug: WHEN productId == 7, THEN RETURN:

    { "id": 7, "name": "Coffee mug", "price": 12.5 }
  2. 2.

    Unknown product on products.findById: WHEN productId = * (any), THEN RETURN null.

  3. 3.

    Saved line on cart_items.insert: WHEN productId = * (any), THEN RETURN:

    { "id": 501 }
  4. 4.

    Expected results for Add to cart: Added: success equals true. Quantity refused: success equals false, message contains "quantity must". No product: success equals false, message equals "Product not found".

Part 9: Write the test cases

  1. 1.

    Open Add to cart → Test → Manage… → New, once per row.

  2. 2.

    One mug: expect Added. Under Database & queue expectations, add cart_items.insert: quantity equals 1.

    { "productId": 7, "quantity": 1 }
  3. 3.

    Eleven mugs: expect Quantity refused.

    { "productId": 7, "quantity": 11 }
  4. 4.

    Zero mugs: expect Quantity refused.

    { "productId": 7, "quantity": 0 }
  5. 5.

    Unknown product: expect No product. Pick Unknown product for products.findById.

    { "productId": 99, "quantity": 1 }

Part 10: Link the requirement

  1. 1.

    Requirements → New requirement: A cart line holds 1 to 10 of a product. Flow Add to cart, test cases One mug, Eleven mugs and Zero mugs.

Part 11: Run it and verify the code

  1. 1.

    Open the flow → Test → Run all. Fix any failing step and run again.

  2. 2.

    Open … and pick Check the generated code.

Check: Every test case is green, and the requirement reads Verified (passing).