home / skills / secondsky / claude-skills / rest-api-design

rest-api-design skill

safe

/plugins/rest-api-design/skills/rest-api-design

This skill helps design RESTful APIs with proper resource naming, methods, status codes, and response formats for developer-friendly interfaces.

npx playbooks add skill secondsky/claude-skills --skill rest-api-design

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

Files (1)

SKILL.md

2.1 KB

---
name: rest-api-design
description: Designs RESTful APIs with proper resource naming, HTTP methods, status codes, and response formats. Use when building new APIs, establishing API conventions, or designing developer-friendly interfaces.
---

# REST API Design

Design RESTful APIs with proper conventions and developer experience.

## Resource Naming

```
# Good - nouns, plural, hierarchical
GET    /api/users
GET    /api/users/123
GET    /api/users/123/orders
POST   /api/users
PATCH  /api/users/123
DELETE /api/users/123

# Bad - verbs, actions in URL
GET    /api/getUsers
POST   /api/createUser
POST   /api/users/123/delete
```

## HTTP Methods

| Method | Purpose | Idempotent |
|--------|---------|------------|
| GET | Read resource | Yes |
| POST | Create resource | No |
| PUT | Replace resource | Yes |
| PATCH | Partial update | Yes |
| DELETE | Remove resource | Yes |

## Status Codes

| Code | Meaning | Use For |
|------|---------|---------|
| 200 | OK | Successful GET, PATCH |
| 201 | Created | Successful POST |
| 204 | No Content | Successful DELETE |
| 400 | Bad Request | Validation errors |
| 401 | Unauthorized | Missing auth |
| 403 | Forbidden | Insufficient permissions |
| 404 | Not Found | Resource doesn't exist |
| 429 | Too Many Requests | Rate limited |

## Response Format

```json
{
  "data": {
    "id": "123",
    "type": "user",
    "attributes": {
      "name": "John",
      "email": "[email protected]"
    }
  },
  "meta": {
    "requestId": "req_abc123"
  }
}
```

## Collection Response

```json
{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8
  },
  "links": {
    "self": "/api/users?page=1",
    "next": "/api/users?page=2"
  }
}
```

## Query Parameters

```
GET /api/products?category=electronics    # Filtering
GET /api/products?sort=-price,name        # Sorting
GET /api/products?page=2&limit=20         # Pagination
GET /api/products?fields=id,name,price    # Field selection
```

## Best Practices

- Use nouns for resources, not verbs
- Version API via URL path (`/api/v1/`)
- Return appropriate status codes
- Include pagination for collections
- Document with OpenAPI/Swagger

Overview

This skill designs RESTful APIs with clear resource naming, correct HTTP methods, meaningful status codes, and consistent response formats. It focuses on developer experience and production-ready conventions for new APIs or API style guides. Use it to establish predictable, well-documented endpoints for teams and clients.

How this skill works

The skill inspects resource models and maps them to noun-based, plural routes, then assigns appropriate HTTP methods (GET, POST, PUT, PATCH, DELETE) and idempotency expectations. It prescribes status codes for common outcomes, standardized JSON response shapes for single resources and collections, and recommended query parameters for filtering, sorting, field selection, and pagination. It also advises on versioning and documentation practices.

When to use it

When building a new REST API to ensure consistent conventions across endpoints
When establishing API design guidelines for a team or organization
When refactoring routes that use verbs or inconsistent naming
When defining response shapes and pagination for client integrations
When creating OpenAPI/Swagger documentation to reflect production behavior

Best practices

Name resources as plural nouns and use hierarchical paths for relationships (e.g., /api/users/{id}/orders)
Choose HTTP methods by intent: GET(read), POST(create), PUT/ PATCH(update), DELETE(remove)
Return appropriate status codes: 200, 201, 204 for success; 400, 401, 403, 404, 429 for errors
Version APIs in the path (e.g., /api/v1/) and keep breaking changes behind new versions
Standardize JSON responses with data, meta, pagination, and links sections for consistency
Support query parameters for filtering, sorting, pagination, and field selection

Example use cases

Designing a user and orders API with endpoints like GET /api/users and GET /api/users/{id}/orders
Specifying response formats for single resources and paginated collections consumed by web clients
Converting verb-based endpoints (e.g., /getUsers) into RESTful resource routes
Defining status code behaviors for create, update, delete, and validation failures
Creating OpenAPI specs that mirror production conventions and pagination metadata

FAQ

Should I use PUT or PATCH to update a resource?

Use PUT for full replacement of a resource and PATCH for partial updates; both should be idempotent where possible.

Where should I put API versioning?

Put the version in the path (e.g., /api/v1/) to make breaking changes explicit and cache-friendly.