Now we have an API

api/README.md

@@ -0,0 +1,222 @@
+# Mailing List API Documentation
+
+REST API for managing mailing lists and members with token-based authentication.
+
+## Base URL
+
+```
+http://localhost:8000
+```
+
+## Authentication
+
+All endpoints (except `/` and `/health`) require Bearer token authentication.
+
+Add the token to request headers:
+```
+Authorization: Bearer your_api_token_here
+```
+
+Set your API token in `.env`:
+```
+API_TOKEN=your_secure_token_here
+```
+
+## Endpoints
+
+### Health Check
+
+**GET** `/health`
+- No authentication required
+- Returns API and database status
+
+```bash
+curl http://localhost:8000/health
+```
+
+### Mailing Lists
+
+**GET** `/lists`
+- Get all mailing lists
+
+```bash
+curl -H "Authorization: Bearer your_token" http://localhost:8000/lists
+```
+
+**GET** `/lists/{list_id}`
+- Get a specific mailing list
+
+```bash
+curl -H "Authorization: Bearer your_token" http://localhost:8000/lists/1
+```
+
+**POST** `/lists`
+- Create a new mailing list
+
+```bash
+curl -X POST http://localhost:8000/lists \
+  -H "Authorization: Bearer your_token" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "list_name": "Developers",
+    "list_email": "dev@lists.sasalliance.org",
+    "description": "Developer discussions",
+    "active": true
+  }'
+```
+
+**PATCH** `/lists/{list_id}`
+- Update a mailing list
+
+```bash
+curl -X PATCH http://localhost:8000/lists/1 \
+  -H "Authorization: Bearer your_token" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "description": "Updated description",
+    "active": false
+  }'
+```
+
+**DELETE** `/lists/{list_id}`
+- Delete a mailing list
+
+```bash
+curl -X DELETE http://localhost:8000/lists/1 \
+  -H "Authorization: Bearer your_token"
+```
+
+### Members
+
+**GET** `/members`
+- Get all members
+
+```bash
+curl -H "Authorization: Bearer your_token" http://localhost:8000/members
+```
+
+**GET** `/members/{member_id}`
+- Get a specific member
+
+```bash
+curl -H "Authorization: Bearer your_token" http://localhost:8000/members/1
+```
+
+**POST** `/members`
+- Create a new member
+
+```bash
+curl -X POST http://localhost:8000/members \
+  -H "Authorization: Bearer your_token" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "John Doe",
+    "email": "john.doe@example.com",
+    "active": true
+  }'
+```
+
+**PATCH** `/members/{member_id}`
+- Update a member
+
+```bash
+curl -X PATCH http://localhost:8000/members/1 \
+  -H "Authorization: Bearer your_token" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "John Q. Doe",
+    "active": true
+  }'
+```
+
+**DELETE** `/members/{member_id}`
+- Delete a member
+
+```bash
+curl -X DELETE http://localhost:8000/members/1 \
+  -H "Authorization: Bearer your_token"
+```
+
+### Subscriptions
+
+**GET** `/lists/{list_id}/members`
+- Get all members of a specific list
+
+```bash
+curl -H "Authorization: Bearer your_token" http://localhost:8000/lists/1/members
+```
+
+**POST** `/subscriptions`
+- Subscribe a member to a list
+
+```bash
+curl -X POST http://localhost:8000/subscriptions \
+  -H "Authorization: Bearer your_token" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "list_email": "community@lists.sasalliance.org",
+    "member_email": "john.doe@example.com",
+    "active": true
+  }'
+```
+
+**DELETE** `/subscriptions?list_email=X&member_email=Y`
+- Unsubscribe a member from a list
+
+```bash
+curl -X DELETE "http://localhost:8000/subscriptions?list_email=community@lists.sasalliance.org&member_email=john.doe@example.com" \
+  -H "Authorization: Bearer your_token"
+```
+
+## Interactive Documentation
+
+Once the API is running, visit:
+
+- **Swagger UI**: http://localhost:8000/docs
+- **ReDoc**: http://localhost:8000/redoc
+
+These provide interactive API documentation where you can test endpoints directly in your browser.
+
+## Example Workflow
+
+1. **Create a new member:**
+```bash
+curl -X POST http://localhost:8000/members \
+  -H "Authorization: Bearer your_token" \
+  -H "Content-Type: application/json" \
+  -d '{"name": "Jane Smith", "email": "jane@example.com", "active": true}'
+```
+
+2. **Create a new mailing list:**
+```bash
+curl -X POST http://localhost:8000/lists \
+  -H "Authorization: Bearer your_token" \
+  -H "Content-Type: application/json" \
+  -d '{"list_name": "Marketing", "list_email": "marketing@lists.sasalliance.org", "active": true}'
+```
+
+3. **Subscribe the member to the list:**
+```bash
+curl -X POST http://localhost:8000/subscriptions \
+  -H "Authorization: Bearer your_token" \
+  -H "Content-Type: application/json" \
+  -d '{"list_email": "marketing@lists.sasalliance.org", "member_email": "jane@example.com"}'
+```
+
+4. **Verify the subscription:**
+```bash
+curl -H "Authorization: Bearer your_token" http://localhost:8000/lists/1/members
+```
+
+## Error Responses
+
+- `401 Unauthorized` - Invalid or missing authentication token
+- `404 Not Found` - Resource not found
+- `400 Bad Request` - Invalid request data
+- `500 Internal Server Error` - Database or server error
+
+## Notes
+
+- All changes take effect immediately in Postfix (no reload needed)
+- Email validation is enforced on all email fields
+- Deleting a list or member also removes associated subscriptions (CASCADE)