Mentor API Reference

The Mentor module of the mentoring tool provides API endpoints that allow front end applications to access and manipulate the data.

All communication with these endpoints must be authenticated. Mentor and Mentee endpoints can only be accessed by admin users. All other endpoints require usernames and passwords for a Mentor account for access.

Currently the authentication scheme used is Basic Auth.

If you’re developing locally remember to create the necessary accounts Account creation. Otherwise, Please contact an admin with superuser permissions to get the relevant accounts created.

A full and up to date version of the api docs can be found by adding /docs/ onto your root url.

Mentees

GET /mentor/mentee

List all mentees.

Example response:

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "2",
      "username": "tony",
      "first_name": "tony",
      "last_name": "",
      "email": "",
      "password": "pbkdf2_sha256$20000$FEIdxqmdW7av$GEB/BUnbRUFj8f7CdNYKaWxGobM2uCJ9sD2/bNSUbn0=",
      "contact_number": "+27123456789"
    }
  ]
}
POST /mentor/mentee

Create a new user with a mentee account. Returns a 201 on success.

Parameters:
  • id (int) – The id for the new user.
  • username (str) – The username for the new user. This will be used to authenticate them.
  • first_name (str) – The first name of the new user.
  • last_name (str) – The surname for the new user.
  • email (str) – The email address for the new user.
  • password (str) – The password for the new user. This will be used to authenticate them.
  • contact_number (str) – The contact number for the new user. This will be used to initiate calls and send messages
GET /mentor/mentee/(mentee_id: str)

Return the details for the mentee.

Example response:

{
  "id": "2",
  "username": "tony",
  "first_name": "tony",
  "last_name": "",
  "email": "",
  "password": "pbkdf2_sha256$20000$FEIdxqmdW7av$GEB/BUnbRUFj8f7CdNYKaWxGobM2uCJ9sD2/bNSUbn0=",
  "contact_number": "+27123456789"
}
PUT /mentor/mentee/(mentee_id: str)

Edit the details for a mentee account.

Accepts the same parameters as POST /mentor/mentee. Returns the same response as GET /mentor/mentee/(mentee_id:str).

Mentors

GET /mentor/mentor

List all mentors.

Example response:

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "1",
      "username": "adam",
      "first_name": "adam",
      "last_name": "",
      "email": "",
      "password": "pbkdf2_sha256$20000$8aa2QhlGJFhX$RV3WqQoN17KoH7SS8r0nUbapHCGqa8hG3I/37xeGuqw=",
      "contact_number": "+27987654321",
      "mentee": 2
    }
  ]
}
POST /mentor/mentor

Create a new user with a mentor account. Returns a 201 on success.

Parameters:
  • id (int) – The id for the new user.
  • username (str) – The username for the new user. This will be used to authenticate them.
  • first_name (str) – The first name of the new user.
  • last_name (str) – The surname for the new user.
  • email (str) – The email address for the new user.
  • password (str) – The password for the new user. This will be used to authenticate them.
  • contact_number (str) – The contact number for the new user. This will be used to initiate calls and send messages
  • mentee (int) – The id for the mentee that has been assigned to this mentor.
GET /mentor/mentor/(mentor_id: str)

Return the details for the mentor.

Example response:

{
  "id": "1",
  "username": "adam",
  "first_name": "adam",
  "last_name": "",
  "email": "",
  "password": "pbkdf2_sha256$20000$8aa2QhlGJFhX$RV3WqQoN17KoH7SS8r0nUbapHCGqa8hG3I/37xeGuqw=",
  "contact_number": "+27987654321",
  "mentee": 2
}
PUT /mentor/mentor/(mentor_id: str)

Edit the details for a mentor account.

Accepts the same parameters as POST /mentor/mentor. Returns the same response as GET /mentor/mentor/(mentor_id:str).

Calls

GET /mentor/call/

List all calls made by the authenticated user.

Example response:

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
      {
          "id": 1,
          "start_time": "2016-01-14T08:56:59.152335Z",
          "end_time": "2016-01-14T08:57:01.749749Z",
          "caller": 1,
          "receiver": 2
      }
  ]
}
POST /mentor/call/

Create a call, with a start_time of the present time, from the currently authenticated mentor to their mentee in the database, then inform the API in use to initiate a call between them. Currently this does not accept any parameters and will ignore any data sent.

Example response:

{
  "id":1,
  "start_time":"2016-01-14T08:56:59.152335Z",
  "end_time":null,
  "caller":1,
  "receiver":2
}
GET /mentor/call/(call_id: str)

Return the call details if the call was made by the authenticated user. Otherwise, return 404.

Example response:

{
  "id":1,
  "start_time":"2016-01-14T08:56:59.152335Z",
  "end_time":"2016-01-14T08:57:01.749749Z",
  "caller":1,
  "receiver":2
}
PUT /mentor/call/(call_id: str)

This access is provided for development and testing purposes only. It should not be used in production. Update the details of a call that was made by the authenticated user. Currently this does not accept any parameters and will ignore any data sent. If the end_time of the call is empty then the request will trigger an automatic update of the end_time of the call to be the current time.

Returns the same response as GET /mentor/call/(call_id:str).

PATCH /mentor/call/(call_id: str)

This access is provided for development and testing purposes only. It should not be used in production. Update the details of a call that was made by the authenticated user. Currently this does not accept any parameters and will ignore any data sent. If the end_time of the call is empty then the request will trigger an automatic update of the end_time of the call to be the current time.

Returns the same response as GET /mentor/call/(call_id:str).

Messages

GET /mentor/message/

List all messages sent or received by the currently authenticated user.

Example response:

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 1,
      "time_sent": "2016-01-14T12:49:12.509174Z",
      "sender_contact": "1234567890",
      "recipient_contact": "1234567891",
      "content": "hi there"
    }
  ]
}
POST /mentor/message/

Create a new message from the currently authenticated mentor to their mentee in the database, then inform the API in use to send this message.

Parameters:
  • sender_id (int) – The if of user who is sending the message.
  • recipient_id (int) – The if of user who should receive the message.
  • content (str) – The content of the message
GET /mentor/message/(message_id: str)

Return the message details if the message was sent or received by the authenticated user. Otherwise, return 404.

Example response:

{
  "id": 1,
  "time_sent": "2016-01-14T12:49:12.509174Z",
  "sender": "sdfsdfsdf",
  "recipient": "sdfsdfsdfsd",
  "content": "hi there"
}

Events

GET /mentor/event/

List all events relevant to the authenticated user.

Example response:

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "occured_at": "2016-02-08T16:00:34.635564Z",
      "event_type": "start_call",
      "description": "Call started",
      "relevant_mentor": 1
    }
  ]
}
GET /mentor/event/(event_id: str)

Return the event details if the event is relevant to the authenticated user. Otherwise, return 404.

Example response:

{
    "occured_at": "2016-02-08T16:00:34.635564Z",
    "event_type": "start_call",
    "description": "Call started",
    "relevant_mentor": 1
}

Tasks

GET /mentor/task/

List all tasks for the authenticated user.

Example response:

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
        "id": 1,
        "mentor": 1,
        "description": "Complete feedback for call at 16:13 on 2016-02-08",
        "link": "",
        "due_date": null,
        "status": "done"
    }
  ]
}
GET /mentor/task/(task_id: str)

Return the details for the task if it is for the authenticated user. Otherwise, return 404.

Example response:

{
  "id": 5,
  "mentor": 1,
  "description": "Complete feedback for call at 16:26 on 2016-02-08",
  "link": "",
  "due_date": null,
  "status": "pending"
}
PUT /mentor/task/(task_id: str)

Update the status for a task relevant to the authenticated user.

Parameters:
  • status (str) – The new status of the task. Valid values: * “pending” * “in-progress” * “done”
PATCH /mentor/task/(task_id: str)

Update the status for a task relevant to the authenticated user.

Accepts the same parameters as PUT /mentor/task/(task_id:str).

Schedule

GET /mentor/schedule/

List all scheduled calls relevant to the authenticated user.

Example response:

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
      {
          "id": 1,
          "created_at": "2016-02-11T15:25:46.291152Z",
          "call_time": "2016-12-23T17:30:00Z",
          "caller": 1,
          "callee": 2
      }
  ]
}
POST /mentor/schedule/

Create a new schedule item for the authenticated mentor to call their mentee. This also immediately sends a message to the mentee to notify them of the call.

Parameters:
  • call_time (str) – The time at which the call should take place. Accepts ISO 8601 format.
GET /mentor/schedule/(schedule_id: str)

Returns the details for the scheduled call if it is relevant to the authenticated user. Otherwise, returns 404.

Example response:

{
  "id": 1,
  "created_at": "2016-02-11T15:25:46.291152Z",
  "call_time": "2016-12-23T17:30:00Z",
  "caller": 1,
  "callee": 2
}
PUT /mentor/schedule/(schedule_id: str)

Change the time of a scheduled call between the authenticated mentor and their mentee. This also immediately sends a message to the mentee to notify them of the change.

Parameters:
  • call_time (str) – The time at which the call should take place. Accepts ISO 8601 format.
PATCH /mentor/schedule/(schedule_id: str)

Change the time of a scheduled call between the authenticated mentor and their mentee. This also immediately sends a message to the mentee to notify them of the change.

Parameters:
  • call_time (str) – The time at which the call should take place. Accepts ISO 8601 format.
DELETE /mentor/schedule/(schedule_id: str)

Delete a scheduled call between the authenticated mentor and their mentee. This also immediately sends a message to the mentee to notify them of the change.