API

Intro

By default, and if installed as described on the front page, drf-sendables comes with two entities: messages and notices.

The following specification refers to the default configuration, but most aspects, such as URL paths, request/response data/format, field names, and searching mechanisms can be adjusted through settings and customized usage.

Some endpoints, as shown below, accept URL query parameters, which are all optional, serving searching purposes. The default search filters are of 3 types: equals, contains, and datetime. The first one requires equality between the search term and the field value and the second one requires the search term being part (substring) of the field value. The third search filter type supports Django field lookups such as sent_on__gte= and requires timestamps as values.

All non-URL request fields are required, and lists cannot be empty. Requests to any endpoint missing a field or having an empty list-type field get responded with 400 Bad Request.

According to default settings all requests must be authenticated, and send notice must be made while authenticated as an administrator user. Requests lacking the required authentication get responded with 403 Forbidden.

Each endpoint only allows for a single HTTP method. If requested using any other, they respond with 405 Method Not Allowed.

The requests and responses can be of any content type that your Django REST Framework project is configured for (either out of the box, or manually), but the following examples use application/json.

Endpoints

You can find a summary of the endpoints at the routing table. Below is their detailed description:

Messages

Messages are sent from a user to others. By default, apart from content and the other fields, they store “sender” information. Endpoints concerning messages require authenticated requests.

POST /messages/send/

Send a message to selected recipients

Example request:

POST /messages/send/ HTTP/1.1

{
    "content": "Hello there",
    "recipient_ids": [
        5, 8, 26
    ]
}

Example response:

HTTP/1.1 201 Created
Content-Type: application/json

{
    "content": "Hello there",
    "recipient_ids": [
        5, 8, 26
    ]
}

Request JSON Object:

• content (string) – the message’s content

Request JSON Array of Objects:

• recipient_ids (integer) – the recipient IDs

Status Codes:

• 201 Created – Success

PATCH /messages/mark-read/

Mark selected received messages as read

Example request:

PATCH /messages/mark-read/ HTTP/1.1

{
    "message_ids": [
        34
    ]
}

Example response:

HTTP/1.1 200 OK

Request JSON Array of Objects:

• message_ids (integer) – the IDs of received messages to be marked

Status Codes:

• 200 OK – Success

PATCH /messages/mark-unread/

Mark selected received messages as unread

Example request:

PATCH /messages/mark-unread/ HTTP/1.1

{
    "message_ids": [
        40, 41, 42
    ]
}

Example response:

HTTP/1.1 200 OK

Request JSON Array of Objects:

• message_ids (integer) – the IDs of received messages to be marked

Status Codes:

• 200 OK – Success

DELETE /messages/delete/

Delete selected received messages

Example request:

DELETE /messages/delete/ HTTP/1.1

{
    "message_ids": [
        11, 15
    ]
}

Example response:

HTTP/1.1 204 No Content

Request JSON Array of Objects:

• message_ids (integer) – the IDs of received messages to be deleted

Status Codes:

• 204 No Content – Success

DELETE /messages/delete-sent/

Delete selected sent messages

Example request:

DELETE /messages/delete-sent/ HTTP/1.1

{
    "message_ids": [
        9, 10, 18
    ]
}

Example response:

HTTP/1.1 204 No Content

Request JSON Array of Objects:

• message_ids (integer) – the IDs of sent messages to be deleted

Status Codes:

• 204 No Content – Success

GET /messages/

List received messages

Example request:

GET /messages/ HTTP/1.1

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "content": "Greetings",
        "id": 3,
        "is_read": false,
        "sender": {
            "id": 14,
            "username": "john"
        },
        "sent_on": "2024-02-15T17:26:30.780074Z"
    },
    {
        "content": "Lorem ipsum",
        "id": 2,
        "is_read": true,
        "sender": {
            "id": 22,
            "username": "helen"
        },
        "sent_on": "2024-02-14T10:01:42.523326Z"
    }
]

Query Parameters:

• content (contains) – message content

• sent_on (datetime) – message “sent on”

• sender__id (equals) – sender ID

• sender__username (equals) – sender username

Status Codes:

• 200 OK – Success

GET /messages/read/

List read received messages

Example request:

GET /messages/read/ HTTP/1.1

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "content": "Congratulations",
        "id": 6,
        "is_read": true,
        "sender": {
            "id": 31,
            "username": "nick"
        },
        "sent_on": "2024-02-16T09:30:47.290671Z"
    },
    {
        "content": "Lorem ipsum",
        "id": 2,
        "is_read": true,
        "sender": {
            "id": 22,
            "username": "helen"
        },
        "sent_on": "2024-02-14T10:01:42.523326Z"
    }
]

Query Parameters:

• content (contains) – message content

• sent_on (datetime) – message “sent on”

• sender__id (equals) – sender ID

• sender__username (equals) – sender username

Status Codes:

• 200 OK – Success

GET /messages/unread/

List unread received messages

Example request:

GET /messages/unread/ HTTP/1.1

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "content": "Have a nice day",
        "id": 15,
        "is_read": false,
        "sender": {
            "id": 23,
            "username": "paul"
        },
        "sent_on": "2024-02-17T19:11:01.281093Z"
    },
    {
        "content": "Greetings",
        "id": 3,
        "is_read": false,
        "sender": {
            "id": 14,
            "username": "john"
        },
        "sent_on": "2024-02-15T17:26:30.780074Z"
    }
]

Query Parameters:

• content (contains) – message content

• sent_on (datetime) – message “sent on”

• sender__id (equals) – sender ID

• sender__username (equals) – sender username

Status Codes:

• 200 OK – Success

GET /messages/sent/

List sent messages

Example request:

GET /messages/sent/ HTTP/1.1

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "content": "Hello, people",
        "id": 37,
        "recipients": [
            {
                "id": 72,
                "username": "jenny"
            },
            {
                "id": 89,
                "username": "chris"
            }
         ],
         "sent_on": "2024-03-22T12:29:10.265971Z"
    },
    {
        "content": "Happy birthday",
        "id": 35,
        "recipients": [
            {
                "id": 55,
                "username": "luke"
            }
         ],
         "sent_on": "2024-03-20T18:40:32.965873Z"
    }
]

Query Parameters:

• content (contains) – message content

• sent_on (datetime) – message “sent on”

• sender__id (equals) – sender ID

• sender__username (equals) – sender username

• recipient_id (equals) – recipient ID

• recipient_username (equals) – recipient username

Status Codes:

• 200 OK – Success

GET /messages/(int: message_id)/

Received message detail

Example request:

GET /messages/3/ HTTP/1.1

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "content": "Greetings",
    "id": 3,
    "is_read": false,
    "sender": {
        "id": 14,
        "username": "john"
    },
    "sent_on": "2024-02-15T17:26:30.780074Z"
}

Status Codes:

• 200 OK – Success

• 404 Not Found – Queried ID not belonging to any received message of the user

GET /messages/sent/(int: message_id)/

Sent message detail

Example request:

GET /messages/sent/37/ HTTP/1.1

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "content": "Hello, people",
    "id": 37,
    "recipients": [
        {
            "id": 72,
            "username": "jenny"
        },
        {
            "id": 89,
            "username": "chris"
        }
    ],
    "sent_on": "2024-03-22T12:29:10.265971Z"
}

Status Codes:

• 200 OK – Success

• 404 Not Found – Queried ID not belonging to any sent message of the user

Notices

Notices are sent from “the system” to users. They don’t have a specific sender, and can only be sent from administrator users. Thus, sending notices requires being authenticated as an administrator user, and the rest of their endpoints require authenticated requests.

POST /notices/send/

Send a notice to selected recipients

Example request:

POST /notices/send/ HTTP/1.1

{
    "content": "Maintenance coming up",
    "recipient_ids": [
        7, 22, 27, 45
    ]
}

Example response:

HTTP/1.1 201 Created
Content-Type: application/json

{
    "content": "Maintenance coming up",
    "recipient_ids": [
        7, 22, 27, 45
    ]
}

Request JSON Object:

• content (string) – the notice’s content

Request JSON Array of Objects:

• recipient_ids (integer) – The recipient IDs

Status Codes:

• 201 Created – Success

PATCH /notices/mark-read/

Mark selected received notices as read

Example request:

PATCH /notices/mark-read/ HTTP/1.1

{
    "notice_ids": [
        19, 28
    ]
}

Example response:

HTTP/1.1 200 OK

Request JSON Array of Objects:

• notice_ids (integer) – the IDs of received notices to be marked

Status Codes:

• 200 OK – Success

PATCH /notices/mark-unread/

Mark selected received notices as unread

Example request:

PATCH /notices/mark-unread/ HTTP/1.1

{
    "notice_ids": [
        2
    ]
}

Example response:

HTTP/1.1 200 OK

Request JSON Array of Objects:

• notice_ids (integer) – the IDs of received notices to be marked

Status Codes:

• 200 OK – Success

DELETE /notices/delete/

Delete selected received notices

Example request:

DELETE /notices/delete/ HTTP/1.1

{
    "notice_ids": [
        11, 15, 47
    ]
}

Example response:

HTTP/1.1 204 No Content

Request JSON Array of Objects:

• notice_ids (integer) – the IDs of received notices to be deleted

Status Codes:

• 204 No Content – Success

GET /notices/

List received notices

Example request:

GET /notices/ HTTP/1.1

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "content": "Feel free to ask us anything",
        "id": 4,
        "is_read": false,
        "sent_on": "2024-01-02T20:01:31.281094Z"
    },
    {
        "content": "Welcome",
        "id": 3,
        "is_read": true,
        "sent_on": "2024-01-02T19:55:03.123811Z"
    }
]

Query Parameters:

• content (contains) – notice content

• sent_on (datetime) – notice “sent on”

Status Codes:

• 200 OK – Success

GET /notices/read/

List read received notices

Example request:

GET /notices/read/ HTTP/1.1

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "content": "Check out this new feature",
        "id": 7,
        "is_read": true,
        "sent_on": "2024-01-04T09:56:38.100680Z"
    },
    {
        "content": "Welcome",
        "id": 3,
        "is_read": true,
        "sent_on": "2024-01-02T19:55:03.123811Z"
    }
]

Query Parameters:

• content (contains) – notice content

• sent_on (datetime) – notice “sent on”

Status Codes:

• 200 OK – Success

GET /notices/unread/

List unread received notices

Example request:

GET /notices/unread/ HTTP/1.1

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "content": "Special offer",
        "id": 10,
        "is_read": false,
        "sent_on": "2024-01-09T21:12:11.101032Z"
    },
    {
        "content": "Feel free to ask us anything",
        "id": 4,
        "is_read": false,
        "sent_on": "2024-01-02T20:01:31.281094Z"
    }
]

Query Parameters:

• content (contains) – notice content

• sent_on (datetime) – notice “sent on”

Status Codes:

• 200 OK – Success

GET /notices/(int: notice_id)/

Received notice detail

Example request:

GET /notices/7/ HTTP/1.1

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "content": "Check out this new feature",
    "id": 7,
    "is_read": true,
    "sent_on": "2024-01-04T09:56:38.100680Z"
}

Status Codes:

• 200 OK – Success

• 404 Not Found – Queried ID not belonging to any received notice of the user