# devRant API overview DevPlace exposes a second REST protocol under `{{ base }}/api` that reproduces the public [devRant](https://devrant.com) API shape on DevPlace data, so legacy devRant clients can run against this server unchanged. Rants are DevPlace posts, comments and votes are the native engagement layer, and every devRant action is funnelled through the same audited helpers as the website (so XP, notifications, and soft-delete all apply). This reference is split across focused pages: - [Authentication & accounts](/docs/devrant-auth.html) - login, registration, the token triple. - [Rants](/docs/devrant-rants.html) - feed, single rant, create, edit, delete, vote, favorite, search. - [Comments](/docs/devrant-comments.html) - read, post, edit, delete, vote. - [Users & avatars](/docs/devrant-users.html) - profiles, username lookup, profile edit, avatars. - [Notifications](/docs/devrant-notifications.html) - the notification feed. - [Client scripts](/docs/devrant-clients.html) - ready-to-run Python and JavaScript clients. ## Base URL and shape Every endpoint lives under `{{ base }}/api` and returns JSON with a `success` boolean. On success the payload sits beside it; on a logical failure the response is `{ "success": false, "error": "..." }`. HTTP status is `200` for logical failures, except a bad login which returns `400` (matching devRant). Requests accept parameters as query string (`GET`/`DELETE`) or as a form body or JSON body (`POST`). ## Integer IDs devRant identifies everything by integer. DevPlace maps those directly onto the auto-increment `id` that every table already carries, so `rant_id` is a post's `id`, `comment_id` is a comment's `id`, and `user_id` is a user's `id`. There is no separate id space to track. ## Authentication model Write operations need the devRant token triple. `POST /api/users/auth-token` with a username (or email) and password returns an `auth_token` object; you then send `user_id`, `token_id`, and `token_key` with every request. Read endpoints (feed, single rant, search, profiles) work without authentication. See [Authentication & accounts](/docs/devrant-auth.html). ## Field mapping at a glance | devRant concept | DevPlace mapping | |-----------------|------------------| | `rant` | post (topic forced to `rant`; `text` is `title` + body when a title exists) | | `tags` | stored verbatim on the post and returned as-is (falls back to `[topic]`) | | `comment` | comment with `target_type = post` | | `vote` (`1`/`-1`/`0`) | upvote / downvote / clear on the native vote layer | | `favorite` / `unfavorite` | bookmark add / remove | | `user_avatar` | a real PNG rendered from the username (see [Users & avatars](/docs/devrant-users.html)) | | `profile.skills` | derived from the user bio (DevPlace has no separate skills field) | ## Availability The protocol is toggled by the `devrant_api_enabled` site setting (default on); when off, every `/api` path returns `404`. Legacy clients hard-coded to `devrant.com` reach this server only through host routing (DNS / reverse-proxy), which is an infrastructure concern.