Help us improve
Share bugs, ideas, or general feedback.
From humaninloop
Designs RESTful API contracts mapping user actions to HTTP endpoints with request/response schemas, error handling, and OpenAPI specs. For new API design, endpoint documentation, and contracts.
npx claudepluginhub joshuarweaver/cascade-ai-ml-agents-agent-framework --plugin deepeshbodh-human-in-loopHow this skill is triggered — by the user, by Claude, or both
Slash command
/humaninloop:patterns-api-contractsThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Design RESTful API contracts that map user actions to endpoints with complete schema definitions and comprehensive error handling. Every user action becomes an endpoint; every endpoint has request/response schemas and error handling.
Guides REST and GraphQL API design including endpoint structure, error handling, versioning, and documentation. Best for new APIs or contract reviews.
Designs REST and GraphQL APIs with OpenAPI 3.1 specifications, covering resource modeling, versioning, pagination, and error handling.
Share bugs, ideas, or general feedback.
Design RESTful API contracts that map user actions to endpoints with complete schema definitions and comprehensive error handling. Every user action becomes an endpoint; every endpoint has request/response schemas and error handling.
humaninloop:patterns-entity-modeling firsthumaninloop:patterns-technical-decisions| User Action | HTTP Method | Endpoint Pattern |
|---|---|---|
| Create resource | POST | /resources |
| List resources | GET | /resources |
| Get single resource | GET | /resources/{id} |
| Update resource | PUT/PATCH | /resources/{id} |
| Delete resource | DELETE | /resources/{id} |
| Perform action | POST | /resources/{id}/{action} |
| Get nested resource | GET | /resources/{id}/children |
| Scenario | Method | Idempotent? |
|---|---|---|
| Create new resource | POST | No |
| Full replacement | PUT | Yes |
| Partial update | PATCH | No |
| Read resource | GET | Yes |
| Remove resource | DELETE | Yes |
| Trigger action | POST | Usually No |
/users, not /user/user-profiles/users/{userId}/users?role=admin/users/{userId}/tasksDocument each endpoint with description, source requirements, request/response schemas, and error cases:
## POST /api/auth/login
**Description**: Authenticate user with email and password
**Source Requirements**: FR-001, US#1
### Request
{JSON request body example}
### Response (200 OK)
{JSON response body example}
### Error Responses
| Status | Code | Description |
|--------|------|-------------|
| 400 | INVALID_INPUT | Missing or malformed fields |
| 401 | INVALID_CREDENTIALS | Wrong email or password |
LoginRequest:
type: object
required:
- email
- password
properties:
email:
type: string
format: email
description: User's email address
password:
type: string
minLength: 8
description: User's password
| Data Model Type | OpenAPI Type | Format |
|---|---|---|
| UUID | string | uuid |
| Text | string | - |
| string | ||
| URL | string | uri |
| Integer | integer | int32/int64 |
| Decimal | number | float/double |
| Boolean | boolean | - |
| Timestamp | string | date-time |
| Date | string | date |
| Enum[a,b,c] | string | enum: [a,b,c] |
Use standard error format with machine-readable codes and human-readable messages.
See ERROR-PATTERNS.md for complete HTTP status codes, error code conventions, and response formats.
| Status | When to Use |
|---|---|
| 400 | Invalid input format |
| 401 | Missing/invalid auth |
| 403 | No permission |
| 404 | Resource missing |
| 409 | State conflict |
| 422 | Business rule violation |
| 429 | Rate limit exceeded |
| 500 | Server error |
For endpoints returning collections, implement pagination, filtering, and sorting.
See PAGINATION-PATTERNS.md for offset vs cursor pagination, filtering operators, and sorting patterns.
GET /api/users?page=1&limit=20&role=admin&sort=-createdAt
When existing API patterns are detected, align new endpoints:
| Aspect | Check For |
|---|---|
| Base path | /api/v1, /api, etc. |
| Auth pattern | Bearer, API key, session |
| Error format | Existing error structure |
| Pagination | page/limit, cursor, offset |
Handle endpoint collisions:
See OPENAPI-TEMPLATE.yaml for a complete, copy-ready template with all sections.
openapi: 3.0.3
info:
title: {Feature Name} API
version: 1.0.0
servers:
- url: /api
paths:
/resource:
get: ...
post: ...
components:
schemas: ...
securitySchemes:
bearerAuth:
type: http
scheme: bearer
security:
- bearerAuth: []
Track endpoint to requirement mapping:
| Endpoint | Method | FR | US | Description |
|---|---|---|---|---|
| /auth/login | POST | FR-001 | US#1 | User login |
| /users/me | GET | FR-004 | US#4 | Get current user |
Validate OpenAPI specifications using the validation script:
python scripts/validate-openapi.py path/to/openapi.yaml
Checks: OpenAPI syntax, REST conventions, error responses, request bodies, operation IDs, security schemes, examples, and descriptions.
Before finalizing API contracts:
❌ /getUsers, /createUser, /deleteUser
✅ /users with appropriate HTTP methods (GET, POST, DELETE)
❌ GET /users/{id}/delete
✅ DELETE /users/{id} or POST /users/{id}/archive
❌ Only documenting 200 OK response ✅ Define all error cases: 400, 401, 403, 404, 409, 422, 500
❌ Mixing /user-profiles, /userSettings, /user_preferences
✅ Pick one style consistently: /user-profiles, /user-settings, /user-preferences
❌ Just returning 400 or 500 for all errors
✅ Specific codes: INVALID_EMAIL, USER_NOT_FOUND, RATE_LIMIT_EXCEEDED
❌ Schema definitions without realistic example values
✅ Include example: fields showing real-world data
❌ Creating new patterns when existing API conventions exist ✅ Always check existing API style (auth, error format, pagination) first