161 lines
2.9 KiB
Markdown
161 lines
2.9 KiB
Markdown
# 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`:
|
|
|
|
```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. |