Sven laptop
45 lines
2.9 KiB
Markdown
45 lines
2.9 KiB
Markdown
# API contract (agent reference)
|
||
|
||
Base URL: `http://localhost:${PORT}`. Use `Authorization: Bearer <token>` on every endpoint except register/login. JSON uses `Content-Type: application/json`; upload routes use `multipart/form-data`.
|
||
|
||
| Method + path | Auth | Input | Result / policy |
|
||
|---|---:|---|---|
|
||
| `POST /auth/register` | no | JSON: `name`, `username`, `email`, `password` | `201 {id}`; strict fields; see password policy below |
|
||
| `POST /auth/login` | no | JSON: `email`, `password` | `200 {id,token,expires_at}`; `401` is generic |
|
||
| `GET /profiles/me` | yes | no body/query | `200 {id,name,username}` for the token user |
|
||
| `GET /profiles/:id` | yes | no body/query | `200 {id,name,username}`; email/password are never exposed |
|
||
| `GET /posts` | yes | no body/query | `200` all posts; ownership does not limit viewing |
|
||
| `GET /posts/me` | yes | no body/query | `200` only posts with `author_id = token.user_id`; each includes `author_username` |
|
||
| `GET /posts/image/:filename` | yes | no body/query | Authenticated image download |
|
||
| `POST /posts/create` | yes | multipart fields: `title`, `text`; optional file `image` | `201` post; `author_id` always comes from token |
|
||
| `PUT /posts/edit?id=<id>` | yes + owner | multipart: optional `title`, `text`, `image`, `remove_image=true\|false` | `200` updated post; upload replaces image; `remove_image=true` clears it; image + remove is invalid |
|
||
| `DELETE /posts/delete?id=<id>` | yes + owner | query: `id` only | `200`; deletes only matching `id AND author_id` and removes stored image |
|
||
| `POST /create_relationship?me=<id>&them=<id>` | yes | query: `me`, `them` only | `200`; `me` must equal token user ID |
|
||
|
||
Post objects include `author_username` and `created_at` (the database creation timestamp), joined from `people.username`; the join is left-sided so an orphaned post is not silently omitted.
|
||
|
||
## Input rules
|
||
|
||
- Any undocumented body or query field returns `400`; do not send `author_id` to create posts.
|
||
- Registration: `name` 1–100 chars; `username` 1–50, no whitespace; `email` 1–254, trimmed/lowercased, valid format, no whitespace, not disposable; `password` 1–128 and at least 12 chars with lower/upper/number/special, no username/email-local-part, common password, triple repeat, or obvious sequence.
|
||
- Login accepts only `email` and `password`; email is trimmed/lowercased; password is not trimmed or otherwise transformed (ordinary whitespace is significant).
|
||
- Passwords, hashes, salts, JWTs, and database details must never be logged or exposed.
|
||
|
||
## Uploads
|
||
|
||
```sh
|
||
curl -X POST http://localhost:3000/posts/create \
|
||
-H "Authorization: Bearer $TOKEN" \
|
||
-F title='Hello' -F text='Body' -F image=@photo.png
|
||
```
|
||
|
||
To edit text/title, replace the image, or remove it:
|
||
|
||
```sh
|
||
curl -X PUT "http://localhost:3000/posts/edit?id=12" \
|
||
-H "Authorization: Bearer $TOKEN" \
|
||
-F text='Updated body' -F remove_image=true
|
||
```
|
||
|
||
Omit `image` and `remove_image` to keep the current image. Stored image URLs require the same Bearer token.
|