---
title: "API Design"
description: "REST API design principles and patterns"
keywords: [api design, rest, endpoints, design patterns]
---

# API Design

REST API design principles and patterns used in TraceRTM.

## REST Principles

### Resource-Based URLs

```python
# Good - resource-based
GET    /api/v1/items
POST   /api/v1/items
GET    /api/v1/items/{id}
PUT    /api/v1/items/{id}
DELETE /api/v1/items/{id}

# Bad - action-based
GET    /api/v1/getItems
POST   /api/v1/createItem
POST   /api/v1/deleteItem
```

### HTTP Methods

| Method | Usage | Idempotent |
|--------|-------|------------|
| `GET` | Retrieve resource | Yes |
| `POST` | Create resource | No |
| `PUT` | Update/replace resource | Yes |
| `PATCH` | Partial update | No |
| `DELETE` | Delete resource | Yes |

## URL Structure

### Nested Resources

```python
# Items in a project
GET /api/v1/projects/{project_id}/items

# Links for an item
GET /api/v1/items/{item_id}/links
```

### Query Parameters

```python
# Filtering
GET /api/v1/items?status=active&view=requirements

# Pagination
GET /api/v1/items?skip=0&limit=50

# Sorting
GET /api/v1/items?sort=-created_at
```

## Request/Response Format

### Request Body

```json
{
  "title": "User Authentication",
  "view": "requirements",
  "status": "draft",
  "description": "System must support login"
}
```

### Response Format

```json
{
  "id": "item_123",
  "title": "User Authentication",
  "view": "requirements",
  "status": "draft",
  "created_at": "2025-01-20T10:30:00Z"
}
```

### Error Response

```json
{
  "error": {
    "code": "validation_error",
    "message": "Invalid request parameters",
    "details": [
      {
        "field": "title",
        "message": "Title is required"
      }
    ]
  }
}
```

## Status Codes

### Success Codes

- `200 OK`: Successful GET, PUT, PATCH
- `201 Created`: Successful POST
- `204 No Content`: Successful DELETE

### Error Codes

- `400 Bad Request`: Invalid request
- `401 Unauthorized`: Authentication required
- `403 Forbidden`: Insufficient permissions
- `404 Not Found`: Resource doesn't exist
- `422 Unprocessable Entity`: Validation error
- `429 Too Many Requests`: Rate limit exceeded
- `500 Internal Server Error`: Server error

## Versioning

### URL Versioning

```python
# Version in URL
/api/v1/items
/api/v2/items
```

### Header Versioning

```http
GET /api/items HTTP/1.1
API-Version: 1
```

## Pagination

### Offset-Based

```json
{
  "total": 150,
  "items": [...],
  "has_more": true,
  "skip": 0,
  "limit": 50
}
```

### Cursor-Based

```json
{
  "data": [...],
  "pagination": {
    "has_more": true,
    "next_cursor": "eyJpZCI6MTAwfQ"
  }
}
```

## Best Practices

### 1. Use Nouns, Not Verbs

```python
# Good
GET /api/v1/items
POST /api/v1/items

# Bad
GET /api/v1/getItems
POST /api/v1/createItem
```

### 2. Consistent Naming

```python
# Use consistent plural nouns
/api/v1/items
/api/v1/projects
/api/v1/links
```

### 3. Filter, Don't Create Endpoints

```python
# Good - use query parameters
GET /api/v1/items?status=active

# Bad - create new endpoint
GET /api/v1/items/active
```

## Related Documentation

- [REST API Overview](/docs/api-reference/rest-api/overview) - API reference
- [REST Principles](./05a-rest-principles) - REST principles
