forked from retoor/devplacepy
58 lines
3.1 KiB
HTML
58 lines
3.1 KiB
HTML
<div class="docs-content" data-render>
|
|
# 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.
|
|
</div>
|