Moving to github

docs/API_DOCUMENTATION.md

@@ -0,0 +1,411 @@
+# 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