{ "openapi": "3.1.0", "info": { "title": "Movies API", "version": "1.0", "description": "A catalog of entirely fictional QA-themed films. Practice multi-parameter filtering, sorting, range validation on ratings, and role-based deletes." }, "servers": [ { "url": "https://funapi.dev/api/movies/v1" } ], "tags": [ { "name": "movies", "description": "now showing: Edge Case (2024)" }, { "name": "uploads", "description": "simulated multipart file uploads" } ], "paths": { "/movies": { "get": { "tags": [ "movies" ], "summary": "List movies (filter, sort, paginate)", "operationId": "mv-list", "responses": { "200": { "description": "Paginated movie list", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid sort or page, or an unknown query parameter (strict mode)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Page out of range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "genre", "in": "query", "required": false, "description": "thriller, drama, comedy, horror, action, documentary.", "schema": { "type": "string" } }, { "name": "year", "in": "query", "required": false, "description": "Exact release year.", "schema": { "type": "integer", "format": "int32" } }, { "name": "sort", "in": "query", "required": false, "description": "\"rating\" or \"year\". Anything else → 400.", "schema": { "type": "string" }, "example": "rating" }, { "name": "page", "in": "query", "required": false, "description": "Page number, 5 per page.", "schema": { "type": "integer", "format": "int32" }, "example": 1 } ] }, "post": { "tags": [ "movies" ], "summary": "Add a movie", "operationId": "mv-post", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "Location": { "schema": { "type": "string", "format": "uri-reference" } } } }, "400": { "description": "Missing title", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat the same key on retry to get the original response instead of a duplicate.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "genre": { "type": "string" }, "year": { "type": "number" }, "rating": { "type": "number" } } }, "example": { "title": "Merge Conflict", "genre": "drama", "year": 2026, "rating": 8 } } } }, "security": [ { "bearerAuth": [] } ] } }, "/movies/{id}": { "get": { "tags": [ "movies" ], "summary": "Get one movie", "operationId": "mv-get", "responses": { "200": { "description": "The movie", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Movie id 1–10.", "schema": { "type": "integer", "format": "int32" }, "example": 9 } ] }, "delete": { "tags": [ "movies" ], "summary": "Remove a movie", "operationId": "mv-del", "responses": { "204": { "description": "Removed" }, "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 id", "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": "Movie id. Viewer token → 403.", "schema": { "type": "integer", "format": "int32" }, "example": 7 }, { "name": "If-Match", "in": "header", "required": false, "description": "Optimistic concurrency check. Mismatch → 412.", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ] } }, "/search": { "get": { "tags": [ "movies" ], "summary": "Full-text search movie titles", "operationId": "mv-search", "responses": { "200": { "description": "Matching movies", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Case-insensitive substring match against the title.", "schema": { "type": "string" }, "example": "edge" } ] } }, "/search/fuzzy": { "get": { "tags": [ "movies" ], "summary": "Typo-tolerant search (fuzzy match, \"did you mean\")", "operationId": "mv-fuzzy-search", "responses": { "200": { "description": "Ranked matches with an editDistance and score; empty data + suggestion if nothing is close enough", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Missing \"q\" or invalid maxDistance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Try a misspelling, e.g. \"eg case\" or \"productoin down\".", "schema": { "type": "string" }, "example": "edge cse" }, { "name": "maxDistance", "in": "query", "required": false, "description": "Max edit distance to accept as a match, default 2. Try 0 to require exact spelling.", "schema": { "type": "integer", "format": "int32" }, "example": 2 } ] } }, "/movies/{id}/rating": { "put": { "tags": [ "movies" ], "summary": "Rate a movie (0–10 inclusive)", "operationId": "mv-rate", "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Rating outside the inclusive 0–10 range", "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 id", "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": "Movie id.", "schema": { "type": "integer", "format": "int32" }, "example": 7 }, { "name": "If-Match", "in": "header", "required": false, "description": "Optimistic concurrency: pass a prior etag (e.g. v1). Mismatch → 412.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "rating": { "type": "number" } } }, "example": { "rating": 6.5 } } } }, "security": [ { "bearerAuth": [] } ] } }, "/movies/{id}/similar": { "get": { "tags": [ "movies" ], "summary": "Get movies with the same genre (recommendation)", "operationId": "mv-similar", "responses": { "200": { "description": "Similar movies", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Movie id.", "schema": { "type": "integer", "format": "int32" }, "example": 8 } ] } }, "/movies/{id}/poster": { "post": { "tags": [ "uploads" ], "summary": "Upload a movie poster (simulated multipart file upload)", "operationId": "mv-poster", "responses": { "201": { "description": "Uploaded", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "Location": { "schema": { "type": "string", "format": "uri-reference" } } } }, "400": { "description": "Missing filename or sizeBytes", "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 movie", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "sizeBytes over the 5 MB limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "contentType is not an accepted image type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Movie id.", "schema": { "type": "integer", "format": "int32" }, "example": 1 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "filename": { "type": "string" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "number" } } }, "example": { "filename": "poster.jpg", "contentType": "image/jpeg", "sizeBytes": 2400000 } } } }, "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 } } } }