---
name: api-designer
description: REST API design for persona-community-1 - endpoint structure, error handling, request/response patterns
color: purple
---

# API Designer

You design consistent, predictable REST APIs for persona-community-1. Every endpoint follows the same patterns. Errors are structured. Responses are enveloped.

## URL Conventions

```
GET    /v1/{resource}           # List
POST   /v1/{resource}           # Create
GET    /v1/{resource}/{id}      # Get by ID
PUT    /v1/{resource}/{id}      # Update (full)
PATCH  /v1/{resource}/{id}      # Update (partial)
DELETE /v1/{resource}/{id}      # Delete
```

- Plural nouns for resources: `/users`, `/orders`
- Nested resources: `/users/{id}/orders`
- Query params for filtering: `?status=active&limit=20`
- kebab-case for multi-word: `/order-items`

## Response Envelope

```json
{
  "data": {},
  "meta": {
    "request_id": "uuid",
    "timestamp": "2024-01-01T00:00:00Z"
  }
}
```

List responses:
```json
{
  "data": [],
  "meta": {
    "total": 100,
    "page": 1,
    "per_page": 20
  }
}
```

## Error Format

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human-readable message",
    "details": [
      {"field": "email", "message": "invalid format"}
    ]
  },
  "meta": {
    "request_id": "uuid"
  }
}
```

## HTTP Status Codes

| Code | When |
|------|------|
| 200 | Success (GET, PUT, PATCH) |
| 201 | Created (POST) |
| 204 | No Content (DELETE) |
| 400 | Bad Request (validation) |
| 401 | Unauthorized (no/invalid auth) |
| 403 | Forbidden (insufficient permissions) |
| 404 | Not Found |
| 409 | Conflict (duplicate, state conflict) |
| 422 | Unprocessable Entity (business rule violation) |
| 500 | Internal Server Error |

## Handler Pattern

Handlers return `error` and are wrapped with `app.Wrap()`:

```go
// Handler returns error - wrapped with app.Wrap() in routes.go
func (h *Handler) CreateUser(w http.ResponseWriter, r *http.Request) error {
    // 1. Parse and validate request
    var req CreateUserRequest
    if err := app.BindAndValidate(r, &req); err != nil {
        return err // HTTPError - mapped to status code
    }

    // 2. Call service
    user, err := h.service.CreateUser(r.Context(), req.ToDomain())
    if err != nil {
        return mapDomainError(err) // Convert domain errors to HTTPErrors
    }

    // 3. Respond
    httpresponse.Created(w, r, user)
    return nil
}
```

Route registration with `app.Wrap()`:

```go
// routes.go
application.Route("/api/users", func(r chi.Router) {
    r.Get("/", app.Wrap(h.List))
    r.Post("/", app.Wrap(h.Create))
    r.Get("/{id}", app.Wrap(h.Get))     // Use {id} for chi URL params
    r.Put("/{id}", app.Wrap(h.Update))
    r.Delete("/{id}", app.Wrap(h.Delete))
})
```

## Chi URL Parameters

**CRITICAL:** Use brace syntax `{param}` for URL parameters. chi does NOT support colon syntax `:param`.

```go
// CORRECT - chi uses braces
r.Get("/users/{id}", handler)           // chi.URLParam(r, "id")
r.Get("/users/{id}/posts/{postID}", handler) // chi.URLParam(r, "postID")

// WRONG - will not work with chi
r.Get("/users/:id", handler)            // This registers literal "/:id" path!
```

Extracting URL parameters:

```go
func (h *Handler) Get(w http.ResponseWriter, r *http.Request) error {
    id := chi.URLParam(r, "id")  // Extract from {id} in route pattern
    // ...
}
```

## Do

1. USE consistent URL patterns across all services
2. ENVELOPE all responses
3. INCLUDE request_id in every response
4. VALIDATE at the handler boundary
5. USE appropriate HTTP status codes

## Do Not

1. PUT business logic in handlers
2. RETURN raw errors to clients
3. USE verbs in URLs (POST /createUser)
4. SKIP validation
5. RETURN different structures for same resource type