REST API Documentation v0.1
The current website that we are on, discuss.selfmade.ninja has REST API endpoints and I am sharing them below. See if you can play with it and understand how it works, and how similar it is to the development that we did etc. If you find some bugs, our doors are open.
Warning: Please be aware that this is a common server that other students also access and get benifitted out of. Whatever you do with this API will be live in the server. If you do anything nasty, we will ban you from all our servers.
Point to note:
1. Variable Endpoints
Some endpoints take variables like https://discuss.selfmade.ninja/api/users/1 and it would have been written in the API doc below like /api/users/:id. You are not supposed to use : in your request. Anything starts with : in API endpoint URI means a variable parameter.
2. Endpoint with queries
Some endpoints take queries for some purposes like filtering, giving a query via GET request or as URL parameter. Such might simply written as a sublist below like filter[user] - description. You should call them like /api/posts?filter[user]=:id to get proper results.
Base URL: https://discuss.selfmade.ninja
Note: Some of the below endpoints require administrator privileges and you might not be able to get an authoratitive response. But most common things you can do from your profile logged in can be done from the APIs too.
Authentication
The API uses token-based authentication. Some endpoints do not require authentication. You can retrieve a token from the /api/token endpoint:
Request
POST /api/token HTTP/1.1
{
"identification": "Toby",
"password": "pass7word"
}
Response:
HTTP/1.1 200 OK
{
"token": "YACub2KLfe8mfmHPcUKtt6t2SMJOGPXnZbqhc3nX",
"userId": "1"
}
You can then pass the token in an Authorization header in subsequent requests:
GET /api/forum HTTP/1.1
Authorization: Token YACub2KLfe8mfmHPcUKtt6t2SMJOGPXnZbqhc3nX
With Postman, you can set the headers directly or under Authorization Tab, use API Key type and for Key, give the value as Authorization and for value Token {token} just like in the above request, and add set it to Headers. Now you can easily do access the below endpoints with the same level of access you have inside this website.
Discussions
GET /api/discussions - get all discussions (sort is -time by default)
- filter[q] - filter by username/gambits (Ex:
/api/discussions?filter[q]={query})
POST /api/discussions - create a new discussionGET /api/discussions/:id - get a discussion by ID (Ex: /api/discussions/1, don’t put : in request. : means a variable)PATCH /api/discussions/:id - update a discussionDELETE /api/discussions/:id - delete a discussion
Posts
GET /api/posts - get all posts.
- filter[discussion] - filter by discussion ID
- filter[user] - filter by user ID
- filter[number] - filter by number (position within the discussion)
- filter[type] - filter by post type
POST /api/posts - create a new postGET /api/posts/:id - get a post by IDPATCH /api/posts/:id - update a postDELETE /api/posts/:id - delete a post
Users
GET /api/users - get all users
- filter[q] - filter by username/gambits
POST /api/users - register a new userGET /api/users/:idOrUsername - get a user by ID or usernamePATCH /api/users/:id - update a userDELETE /api/users/:id - delete a userPOST /api/users/:id/avatar - upload a user avatarDELETE /api/users/:id/avatar - delete a user avatar
Groups
GET /api/groups - get all groupsPOST /api/groups - create a new groupPATCH /api/groups/:id - update a groupDELETE /api/groups/:id - delete a group
Notifications
GET /api/notifications - get all notificationsPATCH /api/notifications/:id - mark a notification as read
Tags
POST /api/tags - create a new tagPATCH /api/tags/:id - update a tagDELETE /api/tags/:id - delete a tag
