REST API Design
Developmentrest-api-designREST API Design is an Agent Skill for development published in the a5c-ai/babysitter repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
RESTful API design principles, versioning, pagination, HATEOAS, and documentation.
QUICK START
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/a5c-ai/babysitter/blob/HEAD/library/specializations/web-development/skills/rest-api-design/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/rest-api-design, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
REST API Design Skill
Expert assistance for designing RESTful APIs following best practices.
Capabilities
- Design resource-oriented APIs
- Implement proper HTTP methods and status codes
- Configure API versioning strategies
- Implement pagination patterns
- Design error responses
- Apply HATEOAS principles
Usage
Invoke this skill when you need to:
- Design new REST APIs
- Review existing API design
- Implement pagination
- Define error handling
- Version APIs
Design Principles
Resource Naming
# Good - nouns, plural
GET /api/users
GET /api/users/123
GET /api/users/123/posts
# Bad - verbs, actions in URL
GET /api/getUsers
GET /api/users/123/getPosts
POST /api/createUser
HTTP Methods
| Method | Usage | Response |
|---|---|---|
| GET | Read resource | 200 OK |
| POST | Create resource | 201 Created |
| PUT | Replace resource | 200 OK |
| PATCH | Partial update | 200 OK |
| DELETE | Remove resource | 204 No Content |
Pagination Response
{
"data": [...],
"meta": {
"page": 1,
"limit": 10,
"total": 100,
"totalPages": 10
},
"links": {
"self": "/api/users?page=1",
"next": "/api/users?page=2",
"prev": null
}
}
Error Response
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Validation failed",
"details": [
{ "field": "email", "message": "Invalid email format" }
]
}
}
Best Practices
- Use proper HTTP status codes
- Implement consistent error responses
- Version APIs from the start
- Document with OpenAPI
Target Processes
- api-design
- backend-development
- microservices-architecture