turbovault-app/docs/API_DOCUMENTATION.md

# TurboVault API Documentation

## Authentication

All API requests require authentication using an API token. You can create API tokens from your account settings page.

### Headers

Include your API token in the `Authorization` header:

```
Authorization: Bearer YOUR_API_TOKEN
```

## Base URL

```
http://localhost:3000/api/v1
```

## Endpoints

### Games

#### List All Games

```
GET /api/v1/games
```

**Query Parameters:**
- `platform_id` - Filter by platform ID
- `genre_id` - Filter by genre ID
- `format` - Filter by format (physical/digital)
- `completion_status` - Filter by completion status
- `search` - Search by game title
- `sort` - Sort by (alphabetical, recent, rated)
- `page` - Page number (default: 1)
- `per_page` - Items per page (default: 25)

**Response:**
```json
[
  {
    "id": 1,
    "title": "The Legend of Zelda: Ocarina of Time",
    "platform": {
      "id": 3,
      "name": "Nintendo 64",
      "abbreviation": "N64"
    },
    "format": "physical",
    "date_added": "2024-01-15",
    "completion_status": "completed",
    "user_rating": 5,
    "condition": "cib",
    "price_paid": "45.00",
    "location": "Shelf A",
    "genres": [
      { "id": 1, "name": "Action" },
      { "id": 2, "name": "Adventure" }
    ],
    "collections": []
  }
]
```

#### Get Single Game

```
GET /api/v1/games/:id
```

**Response:** Same as single game object above

#### Create Game

```
POST /api/v1/games
```

**Request Body:**
```json
{
  "game": {
    "title": "Elden Ring",
    "platform_id": 17,
    "format": "digital",
    "date_added": "2024-03-01",
    "completion_status": "currently_playing",
    "user_rating": 5,
    "digital_store": "PlayStation Store",
    "price_paid": 59.99,
    "genre_ids": [1, 3],
    "notes": "Amazing open world game"
  }
}
```

**Response:** Created game object (status 201)

#### Update Game

```
PUT /api/v1/games/:id
PATCH /api/v1/games/:id
```

**Request Body:** Same as create game

**Response:** Updated game object

#### Delete Game

```
DELETE /api/v1/games/:id
```

**Response:** 204 No Content

#### Bulk Create Games

```
POST /api/v1/games/bulk
```

**Request Body:**
```json
{
  "games": [
    {
      "title": "Game 1",
      "platform_id": 3,
      "format": "physical",
      "condition": "cib"
    },
    {
      "title": "Game 2",
      "platform_id": 17,
      "format": "digital",
      "digital_store": "Steam"
    }
  ]
}
```

**Response:**
```json
{
  "created": 2,
  "failed": 0,
  "details": {
    "created": [ /* array of created game objects */ ],
    "failed": []
  }
}
```

### Collections

#### List All Collections

```
GET /api/v1/collections
```

**Response:**
```json
[
  {
    "id": 1,
    "name": "Nintendo 64 Games",
    "description": "My N64 collection",
    "parent_collection_id": null,
    "games": [ /* array of game objects */ ]
  }
]
```

#### Get Single Collection

```
GET /api/v1/collections/:id
```

#### Create Collection

```
POST /api/v1/collections
```

**Request Body:**
```json
{
  "collection": {
    "name": "PlayStation Games",
    "description": "All my PlayStation titles",
    "parent_collection_id": null
  }
}
```

#### Update Collection

```
PUT /api/v1/collections/:id
PATCH /api/v1/collections/:id
```

#### Delete Collection

```
DELETE /api/v1/collections/:id
```

### Platforms (Read-Only)

#### List All Platforms

```
GET /api/v1/platforms
```

**Response:**
```json
[
  {
    "id": 1,
    "name": "Nintendo 64",
    "abbreviation": "N64",
    "manufacturer": "Nintendo"
  }
]
```

#### Get Single Platform

```
GET /api/v1/platforms/:id
```

### Genres (Read-Only)

#### List All Genres

```
GET /api/v1/genres
```

**Response:**
```json
[
  {
    "id": 1,
    "name": "Action"
  }
]
```

#### Get Single Genre

```
GET /api/v1/genres/:id
```

### API Tokens

#### List Your API Tokens

```
GET /api/v1/api_tokens
```

**Response:**
```json
[
  {
    "id": 1,
    "name": "Mobile App",
    "token": "YOUR_TOKEN_HERE",
    "created_at": "2024-01-01T00:00:00Z",
    "last_used_at": "2024-03-28T12:00:00Z",
    "expires_at": null
  }
]
```

#### Create API Token

```
POST /api/v1/api_tokens
```

**Request Body:**
```json
{
  "api_token": {
    "name": "Mobile App",
    "expires_at": "2025-01-01T00:00:00Z"
  }
}
```

#### Delete API Token

```
DELETE /api/v1/api_tokens/:id
```

## Error Responses

### 401 Unauthorized

```json
{
  "error": "Invalid or missing API token"
}
```

### 404 Not Found

```json
{
  "error": "Record not found"
}
```

### 422 Unprocessable Entity

```json
{
  "errors": [
    "Title can't be blank",
    "Platform must exist"
  ]
}
```

## Rate Limiting

Currently no rate limiting is implemented. This may be added in future versions.

## Data Security

- All API tokens are tied to your user account
- You can only access your own data
- Row Level Security (RLS) is enabled at the database level for additional protection
- API tokens can be revoked at any time from your settings page

## Examples

### cURL Examples

**List games:**
```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
  http://localhost:3000/api/v1/games
```

**Create a game:**
```bash
curl -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"game":{"title":"Halo","platform_id":20,"format":"physical"}}' \
  http://localhost:3000/api/v1/games
```

**Search games:**
```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "http://localhost:3000/api/v1/games?search=zelda&platform_id=3"
```

### JavaScript/Fetch Example

```javascript
const API_URL = 'http://localhost:3000/api/v1';
const API_TOKEN = 'YOUR_TOKEN';

// Fetch all games
async function getGames() {
  const response = await fetch(`${API_URL}/games`, {
    headers: {
      'Authorization': `Bearer ${API_TOKEN}`
    }
  });
  return await response.json();
}

// Create a game
async function createGame(gameData) {
  const response = await fetch(`${API_URL}/games`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_TOKEN}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ game: gameData })
  });
  return await response.json();
}
```

## Notes

- Dates should be in ISO 8601 format (YYYY-MM-DD)
- All timestamps are in UTC
- Boolean values are `true` or `false`
- Numeric values (prices, ratings) should not include commas
- Platform and Genre IDs can be obtained from the `/platforms` and `/genres` endpoints