|
# devRanta
|
|
|
|
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
|
|
```
|
|
make run
|
|
```
|
|
|
|
## Testing
|
|
Tests are only made for methods not requireing authentication.
|
|
I do not see value in mocking requests.
|
|
```
|
|
make test
|
|
```
|
|
|
|
## How to use
|
|
Implementation:
|
|
```
|
|
from devranta.api import Api
|
|
|
|
api = Api(username="optional!", password="optional!")
|
|
|
|
async def list_rants():
|
|
async for rant in api.get_rants():
|
|
print(rant["user_username"], ":", rant["text"])
|
|
```
|
|
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.
|
|
|
|
|