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)
Web App, kind Web frontend.
Part 1: Create the systems
- 1.
Systems → New system, then Create system: - Name
- Cart Service
- Type
- Backend service
- 2.
And again: - Name
- Shop DB
- Type
- Database
Part 2: Declare the cart API
- 1.
Open Cart Service → APIs → Add an API. - 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.
Type the Request body: productId: integer quantity: integer
- 4.
Change the 200 response’s status to 201and type its body:itemId: integer quantity: integer
- 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.
Open Web App → … → Add a dependency…. Consumer Web App, providerCart Service. - 2.
Tick POST /api/v1/cart/itemsand click Connect 1 API.
Part 4: Add the database operations
- 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.
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.
Open Cart Service → APIs. On POST /api/v1/cart/items, click + Logic. - 2.
Add Break Object with these fields, fed from On Request body:productId: integer quantity: integer
- 3.
Add Validate Range on quantity. In Details: Field namequantity, Min1, Max10. Then a BranchQuantity allowed?on itsvalid. - 4.
From False: Return Response 400, body Make Objecterror: stringfrom the validationmessage. - 5.
From True: Query Database products.findById(labelFind product),productIdfrom Break Object. - 6.
From Not found: Return Response 404, body Make Objecterror=Product not found. - 7.
From Found: Database Insert (label Save cart line), Operationcart_items.insert, withproductIdandquantityfrom Break Object. - 8.
Then Return Response 201. Body: Make ObjectitemId: integer+quantity: integer, withitemIdfrom Get Propertyidon the insertresultandquantityfrom Break Object. - 9.
Tick Key step on Find product,Save cart lineand the 201 answer.
Check:
Part 6: Build the button logic on the web app
- 1.
Open Web App → Logic → + Logic. Choose Event / UI action. - Event name
- Press Add to cart
- Name
- Press Add to cart
- 2.
Inputs: - productId
- Whole number
- quantity
- Whole number
- 3.
Return values: - success
- Yes / No
- message
- Text
- 4.
Click Create and open. In Details, make messagenullable (string | null). - 5.
Add Make Object (label Build request) with these fields, connected from On Event:productId: integer quantity: integer
- 6.
Add Call Contract (label Add item) with APIPOST /api/v1/cart/items. Connect the On Event arrow into it andobjectintobody. - 7.
From 201: Return with success= true andmessage= null. - 8.
From 400 and from 404: a Return each, success= false,messagefrom Get Propertyerroronbody. - 9.
From Other: Return with success= false andmessage=Something went wrong.
Check:
Part 7: Create the flow
- 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:
Part 8: Add test data
- 1.
Test data → New test data → products.findById.Coffee mug: WHENproductId==7, THEN RETURN:{ "id": 7, "name": "Coffee mug", "price": 12.5 } - 2.
Unknown productonproducts.findById: WHENproductId= * (any), THEN RETURNnull. - 3.
Saved lineoncart_items.insert: WHENproductId= * (any), THEN RETURN:{ "id": 501 } - 4.
Expected results for Add to cart:Added:successequalstrue.Quantity refused:successequalsfalse,messagecontains"quantity must".No product:successequalsfalse,messageequals"Product not found".
Part 9: Write the test cases
- 1.
Open Add to cart→ Test → Manage… → New, once per row. - 2.
One mug: expectAdded. Under Database & queue expectations, addcart_items.insert:quantityequals1.{ "productId": 7, "quantity": 1 } - 3.
Eleven mugs: expectQuantity refused.{ "productId": 7, "quantity": 11 } - 4.
Zero mugs: expectQuantity refused.{ "productId": 7, "quantity": 0 } - 5.
Unknown product: expectNo product. PickUnknown productfor products.findById.{ "productId": 99, "quantity": 1 }
Part 10: Link the requirement
- 1.
Requirements → New requirement: A cart line holds 1 to 10 of a product.FlowAdd to cart, test casesOne mug,Eleven mugsandZero mugs.
Part 11: Run it and verify the code
- 1.
Open the flow → Test → Run all. Fix any failing step and run again. - 2.
Open … and pick Check the generated code.
Check:
