diff --git a/README.md b/README.md index 6ec5ec9..ea6d610 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,6 @@ # devRanta -devRanta is an async devrant client written in and for Python. -Authentication is only needed for half of the functionality and thus username and password are optional parameters by constructing the main class of this package (Api). - -You can find last packages in tar and wheel format [here](https://retoor.molodetz.nl/retoor/devranta/packages). +devRanta is the best async devRant client written in Python. Authentication is only needed for half of the functionality; thus, the username and password are optional parameters when constructing the main class of this package (Api). You can find the latest packages in tar and wheel format [here](https://retoor.molodetz.nl/retoor/devranta/packages). ## Running ``` @@ -31,3 +28,274 @@ async def list_rants(): See [tests](src/devranta/tests.py) for [examples](src/devranta/tests.py) on how to use. +# devRant API Documentation + +For people wanting to build their own client. + +TODO: document responses. + +## Base URL +`https://devrant.com/api` + +## Authentication +- Uses `dr_token` cookie with `token_id`, `token_key`, and `user_id`. +- Required for endpoints needing user authentication. +- `guid`, `plat`, `sid`, `seid` included in requests for session tracking. + +## Endpoints + +### User Management +1. **Register User** + - **URL**: `/api/users` + - **Method**: POST + - **Parameters**: + - `app`: 3 (constant) + - `type`: 1 (constant) + - `email`: User email + - `username`: User username + - `password`: User password + - `guid`: Unique identifier (from `getMyGuid`) + - `plat`: 3 (constant) + - `sid`: Session start time (from `getSessionStartTime`) + - `seid`: Session event ID (from `getSessionEventId`) + - **Response**: JSON with `success`, `auth_token`, or `error` and `error_field` + - **Description**: Creates a new user account. + +2. **Login User** + - **URL**: `/api/users/auth-token` + - **Method**: POST + - **Parameters**: + - `app`: 3 + - `username`: User username + - `password`: User password + - `guid`: Unique identifier + - `plat`: 3 + - `sid`: Session start time + - `seid`: Session event ID + - **Response**: JSON with `success`, `auth_token`, or `error` + - **Description**: Authenticates user and returns auth token. + +3. **Edit Profile** + - **URL**: `/api/users/me/edit-profile` + - **Method**: POST + - **Parameters**: + - `app`: 3 + - `token_id`: Token ID + - `token_key`: Token key + - `user_id`: User ID + - `guid`, `plat`, `sid`, `seid` + - `profile_about`: User bio + - `profile_skills`: User skills + - `profile_location`: User location + - `profile_website`: User website + - `profile_github`: GitHub username + - **Response**: JSON with `success` + - **Description**: Updates user profile information. + +4. **Forgot Password** + - **URL**: `/api/users/forgot-password` + - **Method**: POST + - **Parameters**: + - `app`: 3 + - `username`: User username + - `guid`, `plat`, `sid`, `seid` + - **Response**: JSON with `success` + - **Description**: Initiates password reset process. + +5. **Resend Confirmation Email** + - **URL**: `/api/users/me/resend-confirm` + - **Method**: POST + - **Parameters**: + - `app`: 3 + - `token_id`, `token_key`, `user_id`, `guid`, `plat`, `sid`, `seid` + - **Response**: JSON with `success` + - **Description**: Resends account confirmation email. + +6. **Delete Account** + - **URL**: `/api/users/me` + - **Method**: DELETE + - **Parameters**: + - `app`: 3 + - `token_id`, `token_key`, `user_id`, `guid`, `plat`, `sid`, `seid` + - **Response**: JSON with `success` + - **Description**: Deletes user account. + +7. **Mark News as Read** + - **URL**: `/api/users/me/mark-news-read` + - **Method**: POST + - **Parameters**: + - `app`: 3 + - `token_id`, `token_key`, `user_id`, `guid`, `plat`, `sid`, `seid` + - `news_id`: News item ID + - **Response**: JSON with `success` + - **Description**: Marks a news item as read for logged-in users. + +### Rants +1. **Get Rant** + - **URL**: `/api/devrant/rants/{rant_id}` + - **Method**: GET + - **Parameters**: + - `app`: 3 + - `token_id`, `token_key`, `user_id`, `guid`, `plat`, `sid`, `seid` + - `last_comment_id`: 999999999999 (optional) + - `links`: 0 (optional) + - **Response**: JSON with `rant` (text, tags) + - **Description**: Retrieves a specific rant by ID. + +2. **Post Rant** + - **URL**: `/api/devrant/rants` + - **Method**: POST + - **Parameters** (FormData): + - `app`: 3 + - `rant`: Rant text + - `tags`: Comma-separated tags + - `token_id`, `token_key`, `user_id` + - `type`: Rant type ID + - `image`: Optional image file (img/gif) + - **Response**: JSON with `success`, `rant_id`, or `error` + - **Description**: Creates a new rant. + +3. **Edit Rant** + - **URL**: `/api/devrant/rants/{rant_id}` + - **Method**: POST + - **Parameters** (FormData): + - `app`: 3 + - `rant`: Rant text + - `tags`: Comma-separated tags + - `token_id`, `token_key`, `user_id` + - `image`: Optional image file + - **Response**: JSON with `success` or `fail_reason` + - **Description**: Updates an existing rant. + +4. **Delete Rant** + - **URL**: `/api/devrant/rants/{rant_id}` + - **Method**: DELETE + - **Parameters**: + - `app`: 3 + - `token_id`, `token_key`, `user_id`, `guid`, `plat`, `sid`, `seid` + - **Response**: JSON with `success` + - **Description**: Deletes a rant. + +5. **Vote on Rant** + - **URL**: `/api/devrant/rants/{rant_id}/vote` + - **Method**: POST + - **Parameters**: + - `app`: 3 + - `token_id`, `token_key`, `user_id`, `guid`, `plat`, `sid`, `seid` + - `vote`: 1 (upvote), -1 (downvote), 0 (remove vote) + - `reason`: Downvote reason ID (required for downvote) + - **Response**: JSON with `success` or `confirmed` (false if unverified) + - **Description**: Votes on a rant. + +6. **Favorite/Unfavorite Rant** + - **URL**: `/api/devrant/rants/{rant_id}/{favorite|unfavorite}` + - **Method**: POST + - **Parameters**: + - `app`: 3 + - `token_id`, `token_key`, `user_id`, `guid`, `plat`, `sid`, `seid` + - **Response**: JSON with `success` + - **Description**: Favorites or unfavorites a rant. + +7. **Get Rant Feed** + - **URL**: `/api/devrant/rants` + - **Method**: GET + - **Parameters**: + - `app`: 3 + - `token_id`, `token_key`, `user_id`, `guid`, `plat`, `sid`, `seid` + - `ids`: JSON string of IDs (optional) + - **Response**: JSON with `success`, `num_notifs` + - **Description**: Retrieves rant feed with notification count. + +### Comments +1. **Get Comment** + - **URL**: `/api/comments/{comment_id}` + - **Method**: GET + - **Parameters**: + - `app`: 3 + - `token_id`, `token_key`, `user_id`, `guid`, `plat`, `sid`, `seid` + - `links`: 0 (optional) + - **Response**: JSON with `comment` (body) + - **Description**: Retrieves a specific comment by ID. + +2. **Post Comment** + - **URL**: `/api/devrant/rants/{rant_id}/comments` + - **Method**: POST + - **Parameters** (FormData): + - `app`: 3 + - `comment`: Comment text + - `token_id`, `token_key`, `user_id` + - `image`: Optional image file (img/gif) + - **Response**: JSON with `success` or `confirmed` (false if unverified) + - **Description**: Posts a comment on a rant. + +3. **Edit Comment** + - **URL**: `/api/comments/{comment_id}` + - **Method**: POST + - **Parameters** (FormData): + - `app`: 3 + - `comment`: Comment text + - `token_id`, `token_key`, `user_id` + - **Response**: JSON with `success` or `fail_reason` + - **Description**: Updates an existing comment. + +4. **Delete Comment** + - **URL**: `/api/comments/{comment_id}` + - **Method**: DELETE + - **Parameters**: + - `app`: 3 + - `token_id`, `token_key`, `user_id`, `guid`, `plat`, `sid`, `seid` + - **Response**: JSON with `success` + - **Description**: Deletes a comment. + +5. **Vote on Comment** + - **URL**: `/api/comments/{comment_id}/vote` + - **Method**: POST + - **Parameters**: + - `app`: 3 + - `token_id`, `token_key`, `user_id`, `guid`, `plat`, `sid`, `seid` + - `vote`: 1 (upvote), -1 (downvote), 0 (remove vote) + - `reason`: Downvote reason ID (required for downvote) + - **Response**: JSON with `success` or `confirmed` (false if unverified) + - **Description**: Votes on a comment. + +### Notifications +1. **Get Notification Feed** + - **URL**: `/api/users/me/notif-feed` + - **Method**: GET + - **Parameters**: + - `app`: 3 + - `token_id`, `token_key`, `user_id`, `guid`, `plat`, `sid`, `seid` + - `ext_prof`: 1 (optional) + - `last_time`: Last notification check time + - **Response**: JSON with `success`, `data` (items, check_time, username_map) + - **Description**: Retrieves user notifications. + +2. **Clear Notifications** + - **URL**: `/api/users/me/notif-feed` + - **Method**: DELETE + - **Parameters**: + - `app`: 3 + - `token_id`, `token_key`, `user_id`, `guid`, `plat`, `sid`, `seid` + - **Response**: JSON with `success` + - **Description**: Clears user notifications. + +## External API +- **Beta List Signup** + - **URL**: `https://www.hexicallabs.com/api/beta-list` + - **Method**: GET (JSONP) + - **Parameters**: + - `email`: User email + - `platform`: Platform name + - `app`: 3 + - **Description**: Signs up user for beta list (external service). + +## Notes +- All endpoints expect `app=3` for identification. +- Authenticated endpoints require `dr_token` cookie with `token_id`, `token_key`, `user_id`. +- `guid`, `plat`, `sid`, `seid` are used for session tracking. +- Image uploads use FormData for rants and comments. +- Downvotes require a reason ID, prompting a modal if not provided. +- Responses typically include `success` boolean; errors include `error` or `fail_reason`. +- Cookies (`dr_token`, `dr_guid`, `dr_session_start`, `dr_event_id`, `dr_feed_sort`, `dr_theme`, `dr_rants_viewed`, `dr_stickers_seen`, `rant_type_filters`, `news_seen`) manage state and preferences. + +