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:

[
  {
    "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:

{
  "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:

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

Response:

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

Collections

List All Collections

GET /api/v1/collections

Response:

[
  {
    "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:

{
  "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:

[
  {
    "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:

[
  {
    "id": 1,
    "name": "Action"
  }
]

Get Single Genre

GET /api/v1/genres/:id

API Tokens

List Your API Tokens

GET /api/v1/api_tokens

Response:

[
  {
    "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:

{
  "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

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

404 Not Found

{
  "error": "Record not found"
}

422 Unprocessable Entity

{
  "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:

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

Create a game:

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:

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

JavaScript/Fetch Example

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