API Guide

This section provides a detailed overview of the Django Announcement API, allowing users to manage announcements efficiently. The API exposes two main endpoints:

Announcements API

The announcement/announcements/ endpoint provides the following features:

• List active announcements:

  Fetches all active announcements for the authenticated user (all announcements for admin users). Controlled by the DJANGO_ANNOUNCEMENT_API_ALLOW_LIST setting.

• Retrieve an announcement:

  Retrieves a specific active announcement by its ID. Controlled by the DJANGO_ANNOUNCEMENT_API_ALLOW_RETRIEVE setting.

Example Responses

Here are some examples of responses for each action:

List announcements with full details:

GET /announcement/announcements/

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

"results": [
     {
         "id": 1,
         "title": "test announcement",
         "content": "some content",
         "category": {
             "id": 1,
             "name": "test category",
             "description": "something!"
         },
         "audience": [
             {
                 "id": 1,
                 "name": "new audience",
                 "description": null
             },
             {
                 "id": 2,
                 "name": "another audience",
                 "description": null
             },
         ],
         "published_at": "2024-10-18T08:49:52Z",
         "expires_at": null,
         "attachment": null,
         "created_at": "2024-10-18T08:49:09Z",
         "updated_at": "2024-10-18T09:10:41.743564Z"
     }
]

If the DJANGO_ANNOUNCEMENT_SERIALIZER_INCLUDE_FULL_DETAILS setting is True, this detailed response will be returned for all users.

List announcements with simplified data:

GET /announcement/announcements/

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

"results": [
     {
         "id": 1,
         "title": "first announcement",
         "content": "some content",
         "category": {
             "id": 1,
             "name": "test category",
             "description": "something!"
         },
         "published_at": "2024-10-18T08:49:52Z",
         "expires_at": null,
         "attachment": null,
         "created_at": "2024-10-18T08:49:09Z",
         "updated_at": "2024-10-18T09:10:41.743564Z"
     },

   ...
]

This response is returned when DJANGO_ANNOUNCEMENT_SERIALIZER_INCLUDE_FULL_DETAILS is set to False. Admins always see full details.

Note

you can exclude Any fields with empty value in the response output by adding this config in your settings.py:

DJANGO_ANNOUNCEMENT_SERIALIZER_EXCLUDE_EMPTY_FIELDS = True

Throttling

The API includes a built-in throttling mechanism that limits the number of requests a user can make based on their role. You can customize these throttle limits in the settings file.

To specify the throttle rates for authenticated users and staff members, add the following in your settings:

DJANGO_ANNOUNCEMENT_AUTHENTICATED_USER_THROTTLE_RATE = "100/day"
DJANGO_ANNOUNCEMENT_STAFF_USER_THROTTLE_RATE = "60/minute"

These settings limit the number of requests users can make within a given timeframe.

Note: You can define custom throttle classes and reference them in your settings.

Filtering, Ordering, and Search

The API supports filtering, ordering, and searching of announcements. Filter Class can be applied optionally, allowing users to narrow down results.

Options include:

• Filtering: By default filtering feature is not included, If you want to use this, you need to add django_filters to your INSTALLED_APPS and provide the path to the AnnouncementFilter class ("django_announcement.api.filters.announcement_filter.AnnouncementFilter"). Alternatively, you can use a custom filter class if needed.

  • Note: for more clarification, refer to the DJANGO_ANNOUNCEMENT_API_FILTERSET_CLASS in Settings section.

• Ordering: Results can be ordered by fields such as id, timestamp, or public.

• Search: You can search fields like verb and description.

These fields can be customized by adjusting the related configurations in your Django settings.

Pagination

The API supports limit-offset pagination, with configurable minimum, maximum, and default page size limits. This controls the number of results returned per page.

Permissions

The base permission for all endpoints is IsAuthenticated, meaning users must be logged in to access the API. You can extend this by creating custom permission classes to implement more specific access control.

For instance, you can allow only specific user roles to perform certain actions.

Parser Classes

The API supports multiple parser classes that control how data is processed. The default parsers include:

• JSONParser

• MultiPartParser

• FormParser

You can modify parser classes by updating the API settings to include additional parsers or customize the existing ones to suit your project.

---

Each feature can be configured through the Django settings file. For further details, refer to the Settings section.