Harbour Market API

A JSON API for the Harbour Night Market: stalls, reviews, saved stalls and orders. It runs on the course server, and everyone has their own market on it, named after their GitHub username:

https://harbour-api.lopin.me/<your-github-username>/api

That's the base URL; every path on this page (/api/stalls, /api/reviews/:id…) is relative to your market, so GET /api/stalls means GET https://harbour-api.lopin.me/<you>/api/stalls. In code, put the base URL in one constant and keep paths relative to it: API = "https://harbour-api.lopin.me/<you>/api", then getJSON("/stalls"), not "/api/stalls" (that would request …/api/api/stalls, a 404). The control page harbour-api.lopin.me checks your URL, sets chaos and resets your market. The same implementation also runs in the exercise editors and the request lab.

Conventions

• Resources, not actions. Nouns in the path, the verb is the method: GET /api/stalls (the collection), GET /api/stalls/mezcal (one item), POST /api/stalls/mezcal/reviews (add to a sub-collection), DELETE /api/reviews/r3. Never /api/getStalls or a GET that changes data.
• Bodies are JSON. Requests with a body (POST, PUT, PATCH) must send Content-Type: application/json, or the server answers 415. Invalid JSON is 400.
• Types are checked. A number sent as a string ("5") is a validation error, not converted.
• Errors have one shape: { "error": "code", "message": "for humans" }, plus "fields": { "name": "message" } on a 422.
• Unknown paths answer 404; a known path with the wrong method answers 405 with an Allow header.
• Changing stalls needs a token in Authorization: Bearer <token>. Two kinds: the admin token harbour-admin-2026 may do everything; a vendor token vendor-<stall id> (e.g. vendor-taco-bike) may only PATCH its own stall. 401: no token, or an invalid one ("who are you?"). 403: a valid token that isn't allowed to do this ("I know who you are, and no"). The tokens are public because this is a course server.
• Times are ISO 8601 strings in UTC: "2026-10-16T19:42:07.311Z".
• Chaos, per market: PUT /api/_chaos with { "latency": 1200, "fail": 0.3 } delays every response by 1.2 s and answers 503 (with Retry-After: 2) to 30 % of requests; GET /api/_chaos shows the settings. ?chaos=1 on any request makes that one request slow and unreliable. The control page harbour-api.lopin.me has switches for both.
• Random 500s: the course server answers about 10 % of requests with 500 { "error": "internal_error" }, on purpose and always (chaos or not). A failed request changed nothing: sending it again is safe. Your page has to cope.
• Reset: POST /api/_reset puts your market back to the seed data. Your data otherwise persists: it's still there tomorrow.
• CORS: every response carries Access-Control-Allow-Origin: *, so a page on any origin (your localhost:8080) can read it; JSON bodies and Authorization trigger a preflight, which is answered.
• Limits, per market: 500 reviews, 500 orders, 60 stalls (then 409 "namespace_full": reset), bodies up to 100 kB (413).

Endpoints

1. GET /api/stalls
2. GET /api/stalls/:id
3. POST /api/stalls 🔑
4. PATCH /api/stalls/:id 🔑
5. DELETE /api/stalls/:id 🔑
6. GET /api/stalls/:id/reviews
7. POST /api/stalls/:id/reviews
8. GET · DELETE /api/reviews/:id
9. GET /api/saved · PUT · DELETE /api/saved/:id
10. POST · GET /api/orders
11. Headers this API uses

The Stall object

{
  "id": "mezcal",              // a slug, never changes
  "name": "Mezcal Moon",
  "tag": "drinks",             // "food" | "music" | "crafts" | "drinks"
  "price": 9,                  // whole euros, 0 = free
  "soldOut": true,
  "featured": true,            // only on some stalls
  "blurb": "Small-batch mezcal and …",
  "rating": 3.7,               // average of its reviews, one decimal, null if none
  "reviewCount": 3
}

fetch("/api/stalls/mezcal", {
  method: "PATCH",
  headers: { "Content-Type": "application/json", Authorization: "Bearer harbour-admin-2026" },
  body: JSON.stringify({ soldOut: false }),
});

{ "id": "r12", "stallId": "mezcal", "author": "Rosa", "rating": 5, "text": "Ask for the espadín.", "createdAt": "2026-10-16T16:22:00.000Z" }

{ "id": "o1", "stallId": "taco-bike", "stallName": "Taco Bike", "name": "Ana", "placedAt": "2026-10-16T19:50:11.020Z", "status": "preparing" }