API Design

knowledge skill

Designs a RESTful API specification from requirements. Produces an OpenAPI 3.0 document defining endpoints, request/response schemas, and parameters.

Worked examples

{"input": {"requirements": "Create API for user management with CRUD operations for users, authentication via JWT, and pagination support.", "version": "1.0.0", "base_path": "/api/v1"}, "output": {"openapi_spec": "openapi: 3.0.3\ninfo:\n title: User Management API\n version: 1.0.0\npaths:\n /users:\n get:\n parameters:\n - in: query\n name: limit\n schema: { type: integer }\n - in: query\n name: offset\n schema: { type: integer }\n responses:\n '200': { description: OK }", "endpoints": ["/users", "/users/{id}"], "status": "valid"}}
{"input": {"requirements": "Design API for order processing with webhook support for payment events.", "version": "2.1.0", "base_path": "/orders"}, "output": {"openapi_spec": "openapi: 3.0.3\ninfo:\n title: Order Processing API\n version: 2.1.0\npaths:\n /orders:\n post:\n requestBody:\n content:\n application/json:\n schema: { $ref: '#/components/schemas/Order' }\n responses:\n '201': { description: Created }\n /webhooks/payments:\n post:\n requestBody:\n content:\n application/json:\n schema: { $ref: '#/components/schemas/PaymentEvent' }\n responses:\n '200': { description: OK }", "endpoints": ["/orders", "/webhooks/payments"], "status": "valid"}}