Skip to content

All endpoints

Base URL: https://corso-api-json.giuseppebosi.com/api/v1. Interactive documentation generated from OpenAPI: Swagger UI; the schema can be downloaded from /api/openapi.json.

Sandbox: the endpoints marked ✍️ require Authorization: Bearer <token> (token from POST /sandbox). The others also work without a token, on the public dataset; with the token they read your copy.

Limit: 30 requests per minute per IP on the public server (120 locally) → 429 with Retry-After. Errors: always {"error": {"code", "message", "details"?}}. Error messages are in Italian; the code values are stable identifiers in English.

Method Path What it does Ch.
GET / index with the main links 1
GET /health service status 1
GET, POST, PUT /echo sends back the method, query, headers and body it received 2
GET /schema tables, columns, primary and foreign keys, counts 5, 12
Method Path What it does Ch.
POST /sandbox creates a private copy of the database → {token, expires_at} (201) 6
GET /sandbox ✍️ information about the token’s sandbox 6
POST /sandbox/reset ✍️ brings the sandbox back to the initial data 6
DELETE /sandbox ✍️ deletes the sandbox (204) 6
GET /sandbox/me 200 with a valid token, 401 without 8
Method Path What it does Ch.
GET /books list with filters (q, author_id, category, tag, min_price, max_price, year_from, year_to, language, in_stock, format), sort (id, title, price, year, pages, created_at, rating; - = desc), page/limit (max 100), expand=author,category,tags 3, 4
GET /books/{id} detail with ETag; expand=author,category,tags,reviews 3, 5, 14
POST /books ✍️ creates (201 + Location) 6
PUT /books/{id} ✍️ replaces in full 6
PATCH /books/{id} ✍️ changes the fields sent 6
DELETE /books/{id} ✍️ deletes (204); 409 book_in_orders if it appears in orders 6, 13
GET /books/{id}/reviews reviews with the customer’s name and city (JOIN); min_rating 5
POST /books/{id}/reviews ✍️ adds a review 6
DELETE /reviews/{id} ✍️ deletes a review 6
GET /export/books.csv, /export/books.ndjson streaming export JSON 11
Method Path What it does Ch.
GET /authors list with books_count; country filter 5
GET /authors/{id} one author 5
GET /authors/{id}/books their books (nested resource) 5
GET /categories flat; ?tree=true as a tree (children) 5
GET /categories/{slug}/books books of the category and its subcategories (deep=false for the category only) 5
GET /customers list; city filter 5
GET /customers/{id} customer with orders_summary 5
POST /customers ✍️ creates; 409 duplicate_email 13
GET /customers/{id}/orders the customer’s orders 5
GET /orders list; status, customer_id, from, to, sort 4
GET /orders/{id} one order; expand=items,items.book,customer (default items) 5
POST /orders ✍️ creates order + lines in a transaction; 422 unknown_book, 409 out_of_stock 13
PATCH /orders/{id} ✍️ changes the status; 409 invalid_transition with allowed 13
DELETE /orders/{id} ✍️ deletes the order and its lines (cascade) 13
Method Path What it does Ch.
GET /search?q= FTS5 full-text with ranking (score) and snippet; limit ≤ 50 9
GET /stats totals, prices, books per category, top authors, orders by status 10
GET /stats/sales group_by = month, category, author, city, from, to 10
POST /query structured JSON filter → parameterized SQL; response with meta.sql 11
POST /sql read-only SELECT (authorizer), max 200 rows, 2 s; params, explain 12
Header Where Meaning
X-Request-Id all request identifier, to quote in logs
ETag, Cache-Control GET /books/{id} (and Cache-Control: no-store with a token) conditional caching (ch. 14)
Location 201 of POST /books, POST /orders URL of the created resource
Retry-After 429 seconds to wait
Access-Control-* all open CORS (ch. 15)
Content-Encoding compressed responses gzip from the API, or zstd from Caddy in production (ch. 14)
Strict-Transport-Security, X-Frame-Options, … production only added by the reverse proxy (Caddy)