API Endpoints documentation

[whit-colm]

An outline of all endpoints which need to be made. These will be documented on the wiki with expected requests and responses.

Notes:

Current API version is askhole.api.dotfile.sh/v0alpha0, this won't be used in code, but in documentation it helps keep track of what's been updated when.

User classes

Permissions are broken into 3 levels; calls may return different information depending on the permission level of the authorization barer token.

1. Students
2. IAs - TAs and Tutors
3. Instructors - Professors, teachers, and other higher order faculty.

Common Objects

Common objects aren't ever exposed themselves, but are used frequently enough throughout the documentation as to necessitate a definitive source in documentation

• [x] author
• [x] message
• [x] report

Object Endpoints

Objects aren't meant to be shown to the user directly, but are necessary to consume in other views. All objects will have a prefix /objs/.

• [x] GET /objs/profile/
  • Perms: All: Get the user ID (i.e. NinerNET ID) and other profile information associated with token.
• [x] GET /objs/tags/
  • Perms: All Get defined system tags, used in threads;
• [x] POST /objs/tags/new/
  • Perms: Instructor: Add new tag;
• [x] DELETE /objs/tags/{tag}/
  • Perms: Instructor: Delete the tag {tag};
• [x] GET /objs/reporttags/
  • Perms: All: Get defined report reasons, used for reports;

User Endpoints

User endpoints are the primary way to get information which should be displayed directly to the user.

• [x] GET /reports/
  • Perms: Instructor: Get a number of the most recently created reports (summary);
• [x] POST /reports/new/
  • Perms: All: Create a new report;
• [x] GET /report/{reportID}/
  • Perms: Instructor: Get the report with UUID {reportID};
• [x] POST /report/{reportID}/hide/
  • Perms: Instructor: Hide the message reported with UUID {reportID};
• [x] GET /threads/
  • Perms: All Get a number of the most recently created threads (summary);
• [x] POST /threads/new/
  • Perms: Student: Create a new thread;
• [x] GET /thread/{threadID}/
  • Perms: All: Get the thread object with the passed UUID {threadID};
• [x] POST /thread/{threadID}/award/
  • Perms: Student (author of thread with threadID only): add author award to message in thread;
  • Perms: IAs || Instructors: add instructor award to post to message in thread;
• [x] POST /thread/{threadID}/new/
  • Perms: All: Post new message into the thread with UUID {threadID};
• [x] POST /thread/{threadID}/{msgID}/vote/
  • Perms: All: Vote on the message with UUID {msgID} in thread with UUID {threadID};

[whit-colm]

Testing badge colours:

• /url/
• /url/
• /url/
• /url/
• /url/
• /url/
• /url/

raw code

```md -  `/url/` -  `/url/` -  `/url/` -  `/url/` -  `/url/` -  `/url/` -  `/url/` ```

[whit-colm]

fields that expect base64 will use a color coded logo

raw code

```  ```

[whit-colm]

Reworked GET /objs/uid/ -> GET /objs/profile/; which also includes a few more fields if useful.

[whit-colm]

As of 19:07:49 EST, api version askhole.api.dotfile.sh/v0alpha0 is complete. Awaiting peer review.