backend

Files (1)

• SKILL.md

SKILL.md (first lines)

# backend

Backend and API design patterns — RESTful and GraphQL API conventions, error handling, pagination, authentication patterns, and database best practices.

## Instructions

Apply these backend practices when building services and APIs:

## Guidelines

### Type Safety

- **Type-safe schemas for every route**: define request and response types with Zod (TypeScript) or Pydantic (Python); validate before any business logic runs
- **Typed database models**: use an ORM with typed models (Prisma, Drizzle, SQLAlchemy); never return raw untyped query results
- **Validated environment variables**: parse and validate all `process.env` / `os.environ` values at application boot using a typed schema — fail fast if required vars are missing or invalid
- **No `any` in controller, service, or repository layers** — every function must have explicit parameter and return types

### Error Handling

- Every route handler must be wrapped in error-catching middleware or use typed `Result`/`Either` types
- Database errors must be caught and converted to domain errors before reaching the controller
- Never expose internal error details (stack traces, DB query strings) to API consumers
- Always return a `traceId` in error responses for debuggability

### Async / Performance

- All I/O operations (DB, HTTP, file) must be async — no synchronous blocking calls in request handlers
- Set explicit timeouts on all outbound HTTP calls and DB queries
- Use connection pooling for database connections; never create a new connection per request

### Security Baseline

- Validate and sanitise every request field — reject unknown fields (strict schema parsing)
- Rate-limit all public endpoints
- Never log request bodies that may contain credentials or PII

---

### RESTful API Design

**Resource naming — use nouns, not verbs:**
```
GET    /users           → list users
POST   /users           → create a user
GET    /users/:id       → get a user
PATCH  /users/:id       → partially update a user
PUT    /users/:id       → replace a user
DELETE /users/:id       → delete a user
GET    /users/:id/posts → list a user's posts
```

**HTTP status codes:**
| Situation | Code |
|-----------|------|
| OK / resource returned | 200 |
| Created | 201 |
| No content (DELETE) | 204 |
| Bad request (validation) | 400 |
| Unauthenticated | 401 |
| Forbidden | 403 |
| Not found | 404 |
| Conflict (duplicate) | 409 |
| Unprocessable entity | 422 |
| Server error | 500 |

**Versioning:** prefix routes with `/v1/`, `/v2/` etc. Never break a published API version.

### Error Response Format

Return consistent, machine-readable errors:
```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      { "field": "email", "message": "Must be a valid email address" }
    ],
    "traceId": "abc123"
  }
}
```

Always include a `traceId` for debuggability in production.

### Pagination

Use cursor-based pagination for large or real-time datasets; offset for simple cases:

**Cursor-based (preferred):**
```json
{
  "data": [...],
  "pagination": {
    "hasNextPage": true,
    "endCursor": "eyJpZCI6MTAwfQ=="
  }
}
```

**Offset-based:**
```json
{
  "data": [...],
  "pagination": {
    "page": 2,
    "perPage": 20,
    "total": 543
  }
}
```

### Authentication Patterns

- **JWT (stateless)**: use short-lived access tokens (15 min) + refresh tokens (7 days stored in `HttpOnly` cookie)
- **Session-based**: server stores session; send `HttpOnly; Secure; SameSite=Strict` cookie
- **API keys**: for machine-to-machine; hash the key in the DB (never store plaintext)
- **OAuth 2.0 / OIDC**: for third-party login; delegate to an identity provider

From Satcomx00-x00/skills-db, MIT.

More from Satcomx00-x00/skills-db