Initial commit

README.md

@@ -1,3 +1,161 @@
-# listthingy-api
+# list thingy API
 
-A list API based off of Symfony for shopping, todos, or other lists
+A list thingy API using plain PHP for shopping, todos, or other lists. Users create a list instantly without any signup.
+They will get a UUID and can share it with friends and collaborate on lists. This API will manage the list with API
+calls and will also run a websocket the iOS and Android apps can connect to.
+
+- No accounts
+- No ads
+- No bloat
+- Code that just works for 15 years
+
+## API
+
+#### Lists
+
+- POST /list
+- GET /list/{uuid}
+- PATCH /list/{uuid}
+- DELETE /list/{uuid}
+
+#### Items
+
+- POST /list/{uuid}/item
+- PATCH /list/{uuid}/item/{id}
+- DELETE /list/{uuid}/item/{id}
+
+## Setup
+
+### Requirements
+
+- PHP 8.0 or higher
+- SQLite3 extension (usually included with PHP)
+
+### Installation
+
+1. Clone the repository
+2. Copy `.env.example` to `.env`:
+
+```bash
+cp .env.example .env
+```
+
+3. (Optional) Edit `.env` to customize configuration
+4. Start the PHP development server:
+
+```bash
+cd public
+php -S localhost:8000
+```
+
+The database will be automatically created on first request at `db/database.sqlite`.
+
+### Configuration
+
+All configuration is managed through the `.env` file:
+
+- `DB_PATH` - Path to SQLite database file (relative or absolute)
+- `CORS_ALLOW_ORIGIN` - CORS allowed origins (default: `*`)
+- `CORS_ALLOW_METHODS` - CORS allowed HTTP methods
+- `CORS_ALLOW_HEADERS` - CORS allowed headers
+- `ERROR_REPORTING` - Enable/disable error reporting (true/false)
+
+## Usage Examples
+
+### Create a List
+
+```bash
+curl -X POST http://localhost:8000/list \
+  -H "Content-Type: application/json" \
+  -d '{"name":"Shopping List","sharable":true}'
+```
+
+Response:
+
+```json
+{
+  "success": true,
+  "data": {
+    "id": 1,
+    "uuid": "a1b2c3d4e5f6...",
+    "name": "Shopping List",
+    "sharable": true,
+    "created_at": "2025-12-12 12:00:00"
+  }
+}
+```
+
+### Get a List with Items
+
+```bash
+curl http://localhost:8000/list/{uuid}
+```
+
+### Update a List
+
+```bash
+curl -X PATCH http://localhost:8000/list/{uuid} \
+  -H "Content-Type: application/json" \
+  -d '{"name":"Updated List Name"}'
+```
+
+### Delete a List
+
+```bash
+curl -X DELETE http://localhost:8000/list/{uuid}
+```
+
+### Add Item to List
+
+```bash
+curl -X POST http://localhost:8000/list/{uuid}/item \
+  -H "Content-Type: application/json" \
+  -d '{"name":"Milk","quantity":2.5,"category":"Dairy"}'
+```
+
+### Update Item
+
+```bash
+curl -X PATCH http://localhost:8000/list/{uuid}/item/{id} \
+  -H "Content-Type: application/json" \
+  -d '{"quantity":3}'
+```
+
+### Delete Item (Soft Delete)
+
+```bash
+curl -X DELETE http://localhost:8000/list/{uuid}/item/{id}
+```
+
+## Models
+
+#### List Model
+
+- id
+- uuid
+- name
+- sharable (boolean)
+- created_at
+
+#### Item Model
+
+- id
+- list_id
+- category
+- quantity (double)
+- name
+- created_at
+- deleted_at
+
+## Architecture
+
+Pure PHP with no dependencies:
+
+- **Database**: SQLite with PDO
+- **Router**: Custom lightweight router
+- **Structure**: Simple MVC pattern
+- **CORS**: Enabled for mobile/web apps
+
+## WebSocket Server
+
+WebSocket support will be implemented separately for real-time collaboration features.