---
title: "API Overview"
description: "Introduction to the TraceRTM REST API - architecture, conventions, and getting started"
---

# API Overview

The TraceRTM REST API provides a powerful, flexible interface for integrating TraceRTM into your development workflow. This guide covers API architecture, conventions, and best practices.

## Architecture

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                         TraceRTM API Architecture                           │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│   Client Applications                                                       │
│   ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐                      │
│   │   CLI    │ │  Web UI  │ │   SDK    │ │  Custom  │                      │
│   └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘                      │
│        │            │            │            │                             │
│        └────────────┴─────┬──────┴────────────┘                             │
│                           │                                                 │
│                     ┌─────▼─────┐                                           │
│                     │   Load    │                                           │
│                     │  Balancer │                                           │
│                     └─────┬─────┘                                           │
│                           │                                                 │
│   ┌───────────────────────┴───────────────────────┐                        │
│   │               API Gateway                      │                        │
│   │  • Authentication  • Rate Limiting            │                        │
│   │  • Request Routing • Response Caching         │                        │
│   └───────────────────────┬───────────────────────┘                        │
│                           │                                                 │
│   ┌───────────────────────┴───────────────────────┐                        │
│   │              Application Layer                 │                        │
│   │  ┌─────────┐ ┌─────────┐ ┌─────────┐         │                        │
│   │  │Projects │ │  Items  │ │  Links  │         │                        │
│   │  └─────────┘ └─────────┘ └─────────┘         │                        │
│   └───────────────────────┬───────────────────────┘                        │
│                           │                                                 │
│   ┌───────────────────────┴───────────────────────┐                        │
│   │                Data Layer                      │                        │
│   │  ┌──────────┐ ┌──────────┐ ┌──────────┐      │                        │
│   │  │PostgreSQL│ │  Neo4j   │ │  Redis   │      │                        │
│   │  │ (Primary)│ │ (Graph)  │ │ (Cache)  │      │                        │
│   │  └──────────┘ └──────────┘ └──────────┘      │                        │
│   └───────────────────────────────────────────────┘                        │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘
```

## API Design Principles

### RESTful Conventions

The API follows REST principles:

1. **Resource-Based URLs**: URLs represent resources, not actions
   ```
   GET /projects          # List projects
   GET /projects/123      # Get specific project
   POST /projects         # Create project
   PATCH /projects/123    # Update project
   DELETE /projects/123   # Delete project
   ```

2. **HTTP Methods**: Methods indicate the action
   - `GET` - Retrieve resources (idempotent)
   - `POST` - Create resources
   - `PATCH` - Partial update (idempotent)
   - `PUT` - Full replacement (idempotent)
   - `DELETE` - Remove resources (idempotent)

3. **HTTP Status Codes**: Codes indicate outcomes
   - `2xx` - Success
   - `4xx` - Client error
   - `5xx` - Server error

### JSON:API Influences

Our API incorporates JSON:API patterns:

```json
{
  "data": {
    "id": "item_123",
    "type": "requirement",
    "attributes": {
      "title": "User Authentication",
      "status": "active"
    },
    "relationships": {
      "project": {
        "data": {"type": "project", "id": "proj_456"}
      },
      "links": {
        "data": [
          {"type": "link", "id": "link_789"}
        ]
      }
    }
  },
  "included": [
    {
      "id": "proj_456",
      "type": "project",
      "attributes": {"name": "MyProject"}
    }
  ]
}
```

## API Versioning

The API uses URL-based versioning:

```
https://api.tracertm.dev/v1/projects
https://api.tracertm.dev/v2/projects  # Future version
```

### Version Lifecycle

| Stage | Description | Duration |
|-------|-------------|----------|
| **Current** | Actively developed, full support | Ongoing |
| **Supported** | Bug fixes, security patches only | 12 months |
| **Deprecated** | No changes, migration warnings | 6 months |
| **Sunset** | Removed from service | - |

### Deprecation Headers

Deprecated endpoints include warning headers:

```http
Deprecation: true
Sunset: Sat, 01 Jan 2026 00:00:00 GMT
Link: <https://api.tracertm.dev/v2/items>; rel="successor-version"
```

## Request Structure

### Required Headers

```http
Authorization: Bearer <token>
Content-Type: application/json
Accept: application/json
```

### Optional Headers

```http
X-Request-ID: req-abc123      # Correlation ID for tracing
X-Idempotency-Key: key-xyz    # Idempotency for POST requests
Accept-Language: en-US        # Localization preference
```

### Request Body Format

```json
{
  "title": "User Authentication",
  "description": "Implement OAuth 2.0 login",
  "type": "requirement",
  "priority": "high",
  "custom_fields": {
    "component": "auth",
    "sprint": 5
  },
  "metadata": {
    "source": "api",
    "imported_from": "jira"
  }
}
```

## Response Structure

### Single Resource

```json
{
  "data": {
    "id": "item_abc123",
    "type": "requirement",
    "title": "User Authentication",
    "description": "Implement OAuth 2.0 login",
    "status": "active",
    "priority": "high",
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T14:20:00Z",
    "created_by": "user_xyz",
    "project_id": "proj_456"
  },
  "meta": {
    "request_id": "req_789",
    "processing_time_ms": 45
  }
}
```

### Resource Collection

```json
{
  "data": [
    {"id": "item_001", "type": "requirement", "title": "Feature A"},
    {"id": "item_002", "type": "requirement", "title": "Feature B"}
  ],
  "meta": {
    "total": 150,
    "page": 1,
    "per_page": 20,
    "total_pages": 8,
    "request_id": "req_789"
  },
  "links": {
    "self": "https://api.tracertm.dev/v1/items?page=1",
    "first": "https://api.tracertm.dev/v1/items?page=1",
    "last": "https://api.tracertm.dev/v1/items?page=8",
    "next": "https://api.tracertm.dev/v1/items?page=2",
    "prev": null
  }
}
```

### Error Response

```json
{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed",
    "details": [
      {
        "field": "title",
        "code": "required",
        "message": "Title is required"
      },
      {
        "field": "priority",
        "code": "invalid_value",
        "message": "Priority must be one of: low, medium, high, critical"
      }
    ],
    "documentation_url": "https://docs.tracertm.dev/errors/validation_error"
  },
  "meta": {
    "request_id": "req_789"
  }
}
```

## Common Patterns

### Idempotency

Use idempotency keys for safe retries:

```bash
curl -X POST "https://api.tracertm.dev/v1/items" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Idempotency-Key: unique-request-id-123" \
  -d '{"title": "New Item"}'
```

The same request with the same key returns the same response:
- First request: Creates resource, returns `201`
- Subsequent requests: Returns cached response, no duplicate creation

### Optimistic Locking

Prevent concurrent update conflicts:

```bash
# Get current version
curl "https://api.tracertm.dev/v1/items/item_123"
# Response includes: "version": 5

# Update with version check
curl -X PATCH "https://api.tracertm.dev/v1/items/item_123" \
  -H "If-Match: 5" \
  -d '{"title": "Updated Title"}'

# If version changed, returns 409 Conflict
```

### Sparse Fieldsets

Request only needed fields:

```bash
# Only return id, title, and status
curl "https://api.tracertm.dev/v1/items?fields=id,title,status"
```

### Include Related Resources

Reduce API calls with includes:

```bash
# Include project and links with item
curl "https://api.tracertm.dev/v1/items/item_123?include=project,links"
```

## Content Types

### Standard JSON

```http
Content-Type: application/json
Accept: application/json
```

### Bulk Operations

```http
Content-Type: application/json
Accept: application/x-ndjson  # Streaming response
```

### File Uploads

```http
Content-Type: multipart/form-data
```

### Export Formats

```bash
# JSON export
curl "https://api.tracertm.dev/v1/export?format=json"

# CSV export
curl "https://api.tracertm.dev/v1/export?format=csv"

# ReqIF export
curl "https://api.tracertm.dev/v1/export?format=reqif"
```

## Security

### HTTPS Required

All API requests must use HTTPS. HTTP requests are rejected.

### Authentication Required

All endpoints (except health check) require authentication.

### CORS

CORS is configured for browser-based applications:

```http
Access-Control-Allow-Origin: https://app.tracertm.dev
Access-Control-Allow-Methods: GET, POST, PATCH, DELETE, OPTIONS
Access-Control-Allow-Headers: Authorization, Content-Type, X-Request-ID
Access-Control-Max-Age: 86400
```

### IP Allowlisting

Enterprise plans support IP allowlisting for API access.

## Health & Status

### Health Check

```bash
curl https://api.tracertm.dev/health

# Response
{
  "status": "healthy",
  "version": "1.5.0",
  "timestamp": "2025-01-15T10:30:00Z"
}
```

### API Status

Check [status.tracertm.dev](https://status.tracertm.dev) for:
- Current API status
- Incident history
- Planned maintenance

## Getting Help

- **Documentation**: [docs.tracertm.dev](https://docs.tracertm.dev)
- **API Reference**: [api.tracertm.dev/docs](https://api.tracertm.dev/docs)
- **Support**: support@tracertm.dev
- **Community**: [community.tracertm.dev](https://community.tracertm.dev)

## Related Documentation

- [Base URL & Endpoints](/docs/api-reference/rest-api/base-url) - Endpoint details
- [Authentication](/docs/api-reference/authentication) - Auth methods
- [Rate Limiting](/docs/api-reference/rest-api/rate-limiting) - Rate limits
- [Errors](/docs/api-reference/rest-api/errors) - Error handling

