Update.
Some checks failed
devranta build / Build (push) Failing after 54s
Details

Browse Source
This commit is contained in:
retoor 2025-08-02 07:11:03 +02:00
parent 000fd98d8d
commit 153d1b2ca5
1 changed files with 272 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

276
README.md
View File

@ -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.