Skip to main content
The Effect Coffee Shop API is a REST API that lets you read the menu, place orders, and manage the lifecycle of each order from placement through pick-up. It is a demo application with no authentication required.

​
Base URL

http://localhost:3000
The port defaults to 3000. You can override it with the COFFEE_HTTP_PORT environment variable before starting the server. 
COFFEE_HTTP_PORT=8080 bun run http

​
Request format

All requests that include a body must set the Content-Type header to application/json. 
curl -X POST http://localhost:3000/orders \
  -H "Content-Type: application/json" \
  -d '{ "customerName": "Alice", "drinkId": "latte", "size": "medium" }'

​
OpenAPI spec

A machine-readable OpenAPI specification is served at runtime: 
curl http://localhost:3000/openapi.json
You can import this URL into tools like Postman, Insomnia, or any OpenAPI-compatible client.

​
Authentication

No authentication is required. This is a local demo application intended for development and learning purposes.

​
Error response format

All errors use Effect’s tagged error schema. Every error response is a JSON object with a _tag discriminant field that identifies the error type, along with additional fields that are specific to that error. 
{
  "_tag": "DrinkNotFoundError",
  "drinkId": "flat-white"
}
_tagHTTP statusWhen it occurs
DrinkNotFoundError404The requested drinkId does not exist in the menu
OrderNotFoundError404No order with the given orderId exists
InvalidOrderInputError400The request body or query parameters failed validation
InvalidOrderStatusTransitionError409The requested status transition is not allowed for the order’s current status
InternalAppError500An unexpected error occurred inside the server

​
Hello world: health check

The fastest way to verify the server is running is to call the health endpoint: 
curl http://localhost:3000/health

{ "status": "ok" }

​
Endpoint groups

The API is organized into three groups.

Health

A single liveness check endpoint that confirms the server is reachable.

Menu

Read the full list of available drinks, their customization options, and base prices.

Orders

Place orders, list and retrieve orders by ID, and advance an order through its lifecycle.

​
All endpoints at a glance

MethodPathDescription
GET/healthServer liveness check
GET/menuList all menu items
POST/ordersPlace a new order
GET/ordersList orders, optionally filtered by status
GET/orders/:orderIdGet a single order by ID
POST/orders/:orderId/start-brewingTransition order to brewing
POST/orders/:orderId/mark-readyTransition order to ready
POST/orders/:orderId/pick-upTransition order to picked-up
POST/orders/:orderId/cancelTransition order to cancelled

Build docs developers (and LLMs) love

Get started for freeTalk to us