OpenParable
Skip to content
← Back to skills

REST API Design

Development
rest-api-design

REST 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.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. 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

MethodUsageResponse
GETRead resource200 OK
POSTCreate resource201 Created
PUTReplace resource200 OK
PATCHPartial update200 OK
DELETERemove resource204 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