home / skills / leavesfly / jimi / api-design

api-design skill

safe

This skill guides RESTful API design using resource-oriented principles, enabling consistent, scalable endpoints with JSON responses and proper error handling.

npx playbooks add skill leavesfly/jimi --skill api-design

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

1.4 KB

---
name: api-design
description: RESTful API design best practices and conventions guide
---

# API Design Skill

This skill provides comprehensive guidance for designing RESTful APIs following industry best practices.

## Core Principles

### 1. Resource-Oriented Design
- Use nouns for resource names (e.g., `/users`, `/products`)
- Avoid verbs in URLs
- Use HTTP methods to represent actions

### 2. HTTP Methods
- **GET**: Retrieve resources
- **POST**: Create new resources
- **PUT**: Update entire resources
- **PATCH**: Partial updates
- **DELETE**: Remove resources

### 3. URL Structure
```
GET    /api/v1/users          - List all users
GET    /api/v1/users/{id}     - Get specific user
POST   /api/v1/users          - Create new user
PUT    /api/v1/users/{id}     - Update user
DELETE /api/v1/users/{id}     - Delete user
```

### 4. Response Format
- Use JSON as default format
- Use camelCase for field names
- Include metadata (pagination, timestamps)

### 5. Error Handling
```json
{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "User ID must be a positive integer",
    "details": []
  }
}
```

### 6. Status Codes
- 200: Success
- 201: Created
- 400: Bad Request
- 401: Unauthorized
- 404: Not Found
- 500: Internal Server Error

## Best Practices
- Version your APIs
- Use pagination for list endpoints
- Implement rate limiting
- Document with OpenAPI/Swagger

Overview

This skill delivers practical guidance for designing RESTful APIs using widely adopted conventions and industry best practices. It focuses on resource-oriented design, clear URL structure, consistent response formats, and robust error handling. The guidance is language-agnostic but uses examples that map easily to Java-based backends. It helps teams produce predictable, maintainable, and versioned APIs.

How this skill works

The skill inspects API design decisions and recommends patterns: noun-based resource naming, correct HTTP method usage, and logical URL hierarchies. It defines response and error formats (JSON, camelCase fields, metadata) and maps common operations to appropriate status codes. It also recommends operational considerations like pagination, rate limiting, and OpenAPI documentation to make APIs discoverable and reliable.

When to use it

When designing new REST APIs for web or mobile clients
When refactoring or standardizing existing endpoints across services
When introducing API versioning or public endpoints
When writing API documentation or OpenAPI specifications
When defining error and response contracts for client teams

Best practices

Design around resources (use nouns) and let HTTP methods express actions
Use consistent URL patterns and include versioning in the path (e.g., /api/v1/)
Return JSON with predictable field naming (camelCase) and include metadata for lists
Use appropriate status codes (201 for created, 400 for bad requests, 404 for missing resources)
Provide structured error payloads with code, message, and optional details
Apply pagination, rate limiting, and document APIs with OpenAPI/Swagger

Example use cases

Designing CRUD endpoints for a user or product service with predictable URIs
Standardizing error responses for a microservices ecosystem to simplify client handling
Creating paginated list endpoints for large datasets (e.g., /api/v1/products?page=2&size=50)
Documenting and publishing an OpenAPI spec to enable client code generation
Implementing partial updates with PATCH and full replacements with PUT

FAQ

Should I use verbs in endpoint paths?

No. Use nouns for resources and let HTTP methods indicate actions to keep URLs intuitive and RESTful.

When do I version my API in the path vs headers?

Path versioning (e.g., /api/v1/) is simple and explicit; header versioning can be used for silent evolution but is harder for tooling and debugging.

How should errors be structured?

Return a JSON object with an error code, human-readable message, and optional details array to help clients programmatically handle failures.