filing-cabinet-api/API.md

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

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:

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.