rest-api-design

Files (1)

• SKILL.md

SKILL.md (first lines)

# REST API Design Skill

## When to use

- Designing or modifying REST API endpoints, URL structures, or routing
- Defining request/response formats, status codes, and error responses
- Planning API versioning strategies or backward compatibility
- Creating API documentation or OpenAPI/Swagger specs
- Understanding general REST principles and patterns

For **project-specific implementation** (shrtner handlers, router configuration, error types), see `../../rules/http-rest-standards.mdc`. For **backend implementation** (Go handlers, services, domain logic), use the `go-backend` skill. For **testing** REST endpoints, use the `testing` skill.

**Note**: This skill provides **general REST design principles** that apply across projects. For shrtner-specific patterns (handler structure, error types, router setup), refer to the rule file above.

## Library Usage

- **Use gorilla/mux** for routing (only external library allowed)
- **Use standard library** for all other functionality:
  - `net/http` for HTTP handling
  - `encoding/json` for JSON encoding/decoding
  - `strconv` for string conversions
  - `context` for context handling
- **Avoid** other external libraries unless absolutely necessary

## REST Design Principles

### Resource-Based URLs

- Use nouns, not verbs: `/users`, `/entities`, `/users/{id}/resources`
- Use plural nouns for collections: `/users` not `/user`
- Use hierarchical paths for relationships: `/users/{userId}/entities/{entityId}`
- Keep URLs simple and intuitive

```go
// ✅ GOOD: Resource-based URLs
GET    /api/v1/users
GET    /api/v1/users/{id}
POST   /api/v1/users
PUT    /api/v1/users/{id}
DELETE /api/v1/users/{id}
GET    /api/v1/users/{id}/entities

// ❌ BAD: Verb-based or inconsistent
GET    /api/v1/getUser/{id}
POST   /api/v1/createUser
GET    /api/v1/user/{id}/getEntities
```

### HTTP Methods

- **GET**: Retrieve resources (idempotent, safe)
- **POST**: Create resources or perform actions
- **PUT**: Replace entire resource (idempotent)
- **PATCH**: Partial update using JSON Merge Patch (RFC 7386) (idempotent when possible)
- **DELETE**: Remove resources (idempotent)

```go
// ✅ GOOD: Proper HTTP method usage
POST   /api/v1/users              // Create user
GET    /api/v1/users/{id}         // Get user
PUT    /api/v1/users/{id}         // Replace user
PATCH  /api/v1/users/{id}         // Partial update (JSON Merge Patch)
DELETE /api/v1/users/{id}         // Delete user

// ❌ BAD: Using POST for everything
POST   /api/v1/users/{id}/get     // Should be GET
POST   /api/v1/users/{id}/delete  // Should be DELETE
```

### Status Codes

- **2xx Success**: 200 (OK), 201 (Created), 204 (No Content)
- **4xx Client Error**: 400 (Bad Request), 401 (Unauthorized), 403 (Forbidden), 404 (Not Found), 409 (Conflict)
- **5xx Server Error**: 500 (Internal Server Error), 502 (Bad Gateway), 503 (Service Unavailable)

```go
// ✅ GOOD: Appropriate status codes
func CreateResource() func(w http.ResponseWriter, r *http.Request) {
    return func(w http.ResponseWriter, r *http.Request) {
        var req CreateRequest
        if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
            // 400 Bad Request - malformed request
            w.WriteHeader(http.StatusBadRequest)
            json.NewEncoder(w).Encode(ErrorResponse{
                Code:    "400",
                Message: "could not decode request body",
            })
            return
        }
        
        // Call service/business logic (implementation-specific)
        resource, err := createResource(r.Context(), req)
        if err != nil {
            if isConflictError(err) {
                // 409 Conflict - duplicate resource
                w.WriteHeader(http.StatusConflict)
                json.NewEncoder(w).Encode(ErrorResponse{
                    Code:    "409",
                    Message: "resource already exists",
                })
                return
            }
            if isValidationError(err) {
                // 400 Bad Request - validation error
                w.WriteHeader(http.StatusBadRequest)
                json.NewEncoder(w).Encode(ErrorResponse{
                    Code:    "400",
                    Message: "invalid input",
                })
                return
            }
            // 500 Internal Server Error - unexpected error
            w.WriteHeader(http.StatusInternalServerError)
            json.NewEncoder(w).Encode(ErrorResponse{
                Code:    "500",
                Message: "an error occurred",
            })
            return
        }

From pedromsmoreira/ai-configs, MIT.

More from pedromsmoreira/ai-configs