{ "openapi": "3.1.0", "info": { "title": "Airline API", "version": "1.0", "description": "Book seats on four questionable flights. Practice 409 seat conflicts and overbooking, a booking state machine (confirmed → checked-in → cancelled), 410 Gone for cancelled bookings, If-Match concurrency and idempotent booking." }, "servers": [ { "url": "https://funapi.dev/api/airline/v1" } ], "tags": [ { "name": "flights", "description": "where the planes pretend to go" }, { "name": "bookings", "description": "a state machine with conflicts" } ], "paths": { "/flights": { "get": { "tags": [ "flights" ], "summary": "List flights, filter by route", "operationId": "al-flights", "responses": { "200": { "description": "Flight list with seat availability", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Origin code, e.g. NYC.", "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "description": "Destination code, e.g. LON.", "schema": { "type": "string" } } ] } }, "/flights/{id}": { "get": { "tags": [ "flights" ], "summary": "Get one flight", "operationId": "al-flight", "responses": { "200": { "description": "The flight", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown flight", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Flight id, e.g. FN101. FN999 → 404.", "schema": { "type": "string" }, "example": "FN101" } ] } }, "/flights/{id}/seats": { "get": { "tags": [ "flights" ], "summary": "Seat map with availability", "operationId": "al-seats", "responses": { "200": { "description": "Seat map", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown flight", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Flight id.", "schema": { "type": "string" }, "example": "FN101" } ] } }, "/flights/{id}/status": { "get": { "tags": [ "flights" ], "summary": "Live-ish flight status (random delays)", "operationId": "al-status", "responses": { "200": { "description": "Status — sometimes delayed. Deterministic mode makes it repeatable.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown flight", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Flight id.", "schema": { "type": "string" }, "example": "FN202" } ] } }, "/bookings": { "post": { "tags": [ "bookings" ], "summary": "Book a seat (409 on conflicts & overbooking)", "operationId": "al-book", "responses": { "201": { "description": "Booked", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "Location": { "schema": { "type": "string", "format": "uri-reference" } } } }, "400": { "description": "Missing passenger or unknown seat", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown flight", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Seat taken, flight cancelled, or flight full (overbooked)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat the same key on retry to replay the original booking instead of double-booking.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "flightId": { "type": "string" }, "passenger": { "type": "string" }, "seat": { "type": "string" } } }, "example": { "flightId": "FN101", "passenger": "Phoebe Buffay", "seat": "1A" } } } }, "security": [ { "bearerAuth": [] } ] } }, "/bookings/{id}": { "get": { "tags": [ "bookings" ], "summary": "Get a booking (410 if cancelled)", "operationId": "al-booking", "responses": { "200": { "description": "The booking", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Never existed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Existed once, cancelled since — Gone", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Booking id. 9001 exists; 8999 was cancelled → 410.", "schema": { "type": "integer", "format": "int32" }, "example": 9001 } ], "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "bookings" ], "summary": "Cancel a booking (admin only, then 410)", "operationId": "al-cancel", "responses": { "204": { "description": "Cancelled — subsequent GETs return 410" }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Viewer token not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown booking", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Cannot cancel after check-in", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Booking id to cancel.", "schema": { "type": "integer", "format": "int32" }, "example": 9001 } ], "security": [ { "bearerAuth": [] } ] } }, "/bookings/{id}/seat": { "put": { "tags": [ "bookings" ], "summary": "Change seat (If-Match concurrency)", "operationId": "al-seat-change", "responses": { "200": { "description": "Seat changed, version bumped", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Unknown seat", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown booking", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Seat taken or booking checked-in", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "If-Match does not match current version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Booking id.", "schema": { "type": "integer", "format": "int32" }, "example": 9001 }, { "name": "If-Match", "in": "header", "required": false, "description": "Optimistic concurrency: pass the booking’s current version (e.g. v1). A stale value → 412.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "seat": { "type": "string" } } }, "example": { "seat": "1C" } } } }, "security": [ { "bearerAuth": [] } ] } }, "/bookings/{id}/checkin": { "post": { "tags": [ "bookings" ], "summary": "Check in (state machine)", "operationId": "al-checkin", "responses": { "200": { "description": "Checked in", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown booking", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Already checked-in, or the flight is cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Booking id. 9002 is already checked-in → 409.", "schema": { "type": "integer", "format": "int32" }, "example": 9001 } ], "security": [ { "bearerAuth": [] } ] } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Use qa-admin-token / qa-viewer-token, or a JWT from POST /auth/v1/login." }, "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Cargo demo key: cargo-key-123." } }, "schemas": { "Error": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "additionalProperties": true } } } }