listthingy-api/README.md

list thingy API

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:

cp .env.example .env

3. (Optional) Edit .env to customize configuration
4. Start the PHP development server:

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

curl -X POST http://localhost:8000/list \
  -H "Content-Type: application/json" \
  -d '{"name":"Shopping List","sharable":true}'

Response:

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

curl http://localhost:8000/list/{uuid}

Update a List

curl -X PATCH http://localhost:8000/list/{uuid} \
  -H "Content-Type: application/json" \
  -d '{"name":"Updated List Name"}'

Delete a List

curl -X DELETE http://localhost:8000/list/{uuid}

Add Item to List

curl -X POST http://localhost:8000/list/{uuid}/item \
  -H "Content-Type: application/json" \
  -d '{"name":"Milk","quantity":2.5,"category":"Dairy"}'

Update Item

curl -X PATCH http://localhost:8000/list/{uuid}/item/{id} \
  -H "Content-Type: application/json" \
  -d '{"quantity":3}'

Delete Item (Soft Delete)

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.