{ "openapi": "3.1.0", "info": { "title": "Marvel API", "version": "1.0", "description": "Marvel heroes, villains and mission assignments. Practice CRUD, Bearer auth, nested resources, pagination, and state-transition conflicts (409)." }, "servers": [ { "url": "https://funapi.dev/api/marvel/v1" } ], "tags": [ { "name": "heroes", "description": "six Avengers across two teams" }, { "name": "villains", "description": "threat levels, some defeated" }, { "name": "missions", "description": "assign heroes, then complete them" } ], "paths": { "/heroes": { "get": { "tags": [ "heroes" ], "summary": "List heroes (paginated, filter by team)", "operationId": "al-list", "responses": { "200": { "description": "Paginated hero list", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Page out of range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number, default 1.", "schema": { "type": "integer", "format": "int32" }, "example": 1 }, { "name": "team", "in": "query", "required": false, "description": "\"Avengers\" or \"Avengers Reserve\".", "schema": { "type": "string" } } ] }, "post": { "tags": [ "heroes" ], "summary": "Recruit a new hero", "operationId": "al-post", "responses": { "201": { "description": "Recruited", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "Location": { "schema": { "type": "string", "format": "uri-reference" } } } }, "400": { "description": "Missing name or power", "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": { "name": { "type": "string" }, "power": { "type": "string" }, "team": { "type": "string" } } }, "example": { "name": "Scarlet Witch", "power": "chaos magic", "team": "Avengers Reserve" } } } }, "security": [ { "bearerAuth": [] } ] } }, "/heroes/{id}": { "get": { "tags": [ "heroes" ], "summary": "Get one hero", "operationId": "al-get", "responses": { "200": { "description": "The hero", "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": "Hero id. Try 999 for a 404.", "schema": { "type": "integer", "format": "int32" }, "example": 1 } ] }, "put": { "tags": [ "heroes" ], "summary": "Update a hero", "operationId": "al-put", "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Empty body / invalid JSON", "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": "Hero id to update.", "schema": { "type": "integer", "format": "int32" }, "example": 6 }, { "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": { "team": { "type": "string" } } }, "example": { "team": "Avengers" } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "heroes" ], "summary": "Retire a hero", "operationId": "al-del", "responses": { "204": { "description": "Retired" }, "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": "Hero id. Viewer token → 403.", "schema": { "type": "integer", "format": "int32" }, "example": 6 }, { "name": "If-Match", "in": "header", "required": false, "description": "Optimistic concurrency check. Mismatch → 412.", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ] } }, "/heroes/{id}/missions": { "get": { "tags": [ "heroes" ], "summary": "Get a hero's assigned missions (nested resource)", "operationId": "al-hero-missions", "responses": { "200": { "description": "Matching missions", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown hero", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Hero id.", "schema": { "type": "integer", "format": "int32" }, "example": 2 } ] } }, "/villains": { "get": { "tags": [ "villains" ], "summary": "List villains, filter by threat level", "operationId": "al-villains", "responses": { "200": { "description": "Villain list", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid threatLevel value", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "threatLevel", "in": "query", "required": false, "description": "medium, high, or extreme.", "schema": { "type": "string" } } ] } }, "/missions": { "post": { "tags": [ "missions" ], "summary": "Assign heroes to a new mission", "operationId": "al-mission-post", "responses": { "201": { "description": "Mission created", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "Location": { "schema": { "type": "string", "format": "uri-reference" } } } }, "400": { "description": "Missing title or unknown heroIds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "heroIds": { "type": "array", "items": { "type": "number" } } } }, "example": { "title": "Stop Thanos from acquiring the last Infinity Stone", "heroIds": [ 1, 3 ] } } } }, "security": [ { "bearerAuth": [] } ] } }, "/missions/{id}": { "get": { "tags": [ "missions" ], "summary": "Get one mission", "operationId": "al-mission-get", "responses": { "200": { "description": "The mission", "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": "Mission id from POST /missions.", "schema": { "type": "integer", "format": "int32" }, "example": 1 } ] } }, "/missions/{id}/complete": { "post": { "tags": [ "missions" ], "summary": "Mark a mission complete (409 if already complete)", "operationId": "al-mission-complete", "responses": { "200": { "description": "Marked complete", "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 id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Mission is already complete", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Mission id.", "schema": { "type": "integer", "format": "int32" }, "example": 1 } ], "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 } } } }