Roles

This section outlines the various roles within django-notification-api, detailing their permissions, actions, and throttling limits for both API and admin interactions. By defining role-based access control, the system ensures secure and efficient management of notifications, while providing flexibility for different user levels. Whether for anonymous users with no access, authenticated users interacting via the API, or administrators managing the notification system, these roles offer a structured way to control who can create, retrieve, update, or delete notifications. This role-based framework helps maintain security, optimize performance, and support scalable system management.

API Roles

This section defines the user roles that interact with the dj-notification-api and outlines their specific permissions, throttling limits, and actions available via the API. These roles allow for fine-grained control over who can create, retrieve, update, and delete notifications, and ensure that the system is scalable and secure for various levels of users.

1. Anonymous Users

Anonymous users are those who are not authenticated within the Django application. By default, anonymous users do not have access to most of the features in the notification API.

Permissions:

  • List Notifications: ❌ (Disabled)

  • Retrieve Notifications: ❌ (Disabled)

  • Create Notifications: ❌ (Disabled)

  • Delete/Modify Notifications: ❌ (Disabled)

Throttling:

  • Rate Limit: N/A (No access)

Use Case:

Anonymous users are generally restricted from interacting with the notification system.

2. Authenticated Users

Authenticated users are regular users who have logged in to the Django application. They have basic permissions to view notifications.

Permissions:

  • List Notifications: ✅ (If DJANGO_NOTIFICATION_API_ALLOW_LIST is set to True)

  • Retrieve Notifications: ✅ (If DJANGO_NOTIFICATION_API_ALLOW_RETRIEVE is set to True)

  • Create Notifications: ❌ (Disabled by default)

  • Delete/Modify Notifications: ❌ (Disabled by default)

Throttling:

  • Rate Limit: 30/minute (Configurable via DJANGO_NOTIFICATION_AUTHENTICATED_USER_THROTTLE_RATE)

Use Case:

Authenticated users can view and retrieve their own notifications, but they cannot create or delete notifications unless explicitly allowed.

3. Staff Users (Admin)

Staff users (admin or elevated users) have more privileges in terms of creating and managing notifications, depending on the configuration of the settings.

Permissions:

  • List Notifications: ✅ (If allowed by DJANGO_NOTIFICATION_API_ALLOW_LIST)

  • Retrieve Notifications: ✅ (If allowed by DJANGO_NOTIFICATION_API_ALLOW_RETRIEVE)

  • Create Notifications: ❌

  • Modify Notifications: ❌

  • Delete Notifications: ✅ (If DJANGO_NOTIFICATION_API_INCLUDE_HARD_DELETE is set to True)

Throttling:

  • Rate Limit: 100/minute (Configurable via DJANGO_NOTIFICATION_STAFF_USER_THROTTLE_RATE)

Use Case:

Staff users are responsible for maintaining the notification system. They can create, edit, and delete notifications for the user base.

Customizing Roles with Extra Permissions

The system also allows for more fine-grained control through the DJANGO_NOTIFICATION_API_EXTRA_PERMISSION_CLASS setting. You can define additional custom permission classes that extend the base permissions, adding conditions for API access. This is useful when specific user groups or roles require specialized access to certain notification features.

Example: You can create a custom permission class to restrict access to only users with a particular role or attribute:

DJANGO_NOTIFICATION_API_EXTRA_PERMISSION_CLASS = (
    "myapp.permissions.CustomPermissionClass"
)

Role-Based Throttling

The package offers a role-based throttling system, allowing you to configure different API request rates for different user roles:

  • Authenticated Users: Throttled at a rate of 30 requests/minute by default.

  • Staff Users: Throttled at a rate of 100 requests/minute by default.

  • Superusers: No throttling applied.

This ensures that the API remains performant, and users with higher permissions are allowed to make more requests.

Example Throttle Configuration:

DJANGO_NOTIFICATION_AUTHENTICATED_USER_THROTTLE_RATE = "30/minute"
DJANGO_NOTIFICATION_STAFF_USER_THROTTLE_RATE = "100/minute"
DJANGO_NOTIFICATION_API_THROTTLE_CLASS = (
    "django_notification.api.throttlings.role_base_throttle.RoleBasedUserRateThrottle"
)

Summary of Role Capabilities

Role

List Notifications

Retrieve Notifications

Create Notifications

Modify Notifications

Delete Notifications

Throttle Rate

Anonymous

❌

❌

❌

❌

❌

N/A

Authenticated

✅

✅

❌

❌

❌

30/minute

Staff

✅

✅

✅ (Optional)

❌

✅ (Optional)

100/minute

By configuring these roles, you ensure that each user type has access to the appropriate level of functionality within the notification API, maintaining security and system stability.

Admin Role

This section outlines the role of admins in interacting with the dj-notification-api through the Django admin panel. Admin users have elevated privileges to manage notifications and their associated data.

1. Admin Users

Admin users have comprehensive permissions to manage notifications, including creating, updating, deleting, and viewing both active and deleted notifications.

Permissions:

  • Create Notifications: ✅ (If DJANGO_NOTIFICATION_ADMIN_HAS_ADD_PERMISSION is set to True)

  • Modify Notifications: ✅ (If DJANGO_NOTIFICATION_ADMIN_HAS_CHANGE_PERMISSION is set to True)

  • Delete Notifications: ✅ (If DJANGO_NOTIFICATION_ADMIN_HAS_DELETE_PERMISSION is set to True)

Use Case:

Admin users are responsible for maintaining the notification system, including marking notifications as sent, managing recipients, and tracking when notifications are seen.

Admin Actions

  • Mark as Sent: Admins can mark selected notifications as sent, updating the is_sent field to True and receiving feedback on the number of notifications updated.

Inline Admin Interfaces

The admin panel includes two inline interfaces: - NotificationRecipientInline: Manage recipients associated with notifications directly. - NotificationSeenInline: View records of when notifications were seen by recipients.

List Display

The list view for notifications includes fields such as: - ID: Unique identifier for each notification. - Title: Summary of the notification. - Sent Status (is_sent): Indicates if the notification has been sent. - Public Status: Indicates if the notification is public. - Timestamp: Creation time of the notification.

Filtering

Admins can filter notifications by: - is_sent - public - timestamp

Search Functionality

Search for notifications using: - ID - Recipient Username Field - Group Name

Pagination

The admin list view displays 10 notifications per page by default for better management of large lists.

Permissions Configuration

Control admin permissions through settings: - DJANGO_NOTIFICATION_ADMIN_HAS_ADD_PERMISSION: Controls “add” action. - DJANGO_NOTIFICATION_ADMIN_HAS_CHANGE_PERMISSION: Controls “change” action. - DJANGO_NOTIFICATION_ADMIN_HAS_DELETE_PERMISSION: Controls “delete” action.

Deleted Notifications

Admin can manage deleted notifications with features like:

  • List Display showing: - Notification ID - Title - Deleted by - Deleted at

  • List Filters by deleted_at timestamp.

  • Pagination showing 10 deleted notifications per page.

Search Functionality for Deleted Notifications

Search deleted notifications using: - Notification ID - User Username Field

Search Logic

  • Notification ID Search: Searches by ID if the term is a number.

  • Username Search: Filters based on the username field if the term is a string.