Notification Management

Author: ~~Grok,~~Josh AIS. ~~Assistant~~Sakweli, Backend Lead Team
Last Updated: 2025-10-18
Version: v1.0

Base URL: https://api.nextgate.com/api/v1

Short Description: The Notification Management API enables authenticated users to manage their in-app notifications, including retrieving paginated lists of notifications, viewing unread notifications, getting summary counts, marking notifications as read, and deleting them. This API is designed for users to interact with their personal notification data securely and efficiently. It supports operations for individual, batch, and bulk actions on notifications.

Hints:

All endpoints require Bearer Token authentication (Authorization: Bearer your_token).
Responses use UTC timestamps in ISO 8601 format (e.g., 2025-10-18T11:32:00Z).
Rate limiting: 100 requests per minute per user.
Pagination is used for list endpoints with default page=1 and size=20.
Testing/sandbox information: Use the sandbox environment at https://sandbox.nextgate.com/api/v1 for development.

Standard Response Format

All API responses follow a consistent structure using our Globe Response Builder pattern:

Success Response Structure

{
  "success": true,
  "httpStatus": "OK",
  "message": "Operation completed successfully",
  "action_time": "2025-10-18T11:32:00Z",
  "data": {
    // Actual response data goes here
  }
}

Error Response Structure

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Error description",
  "action_time": "2025-10-18T11:32:00Z",
  "data": "Error description" // or detailed error object
}

Standard Response Fields

Field	Type	Description
`success`	boolean	Always `true` for successful operations, `false` for errors
`httpStatus`	string	HTTP status name (OK, BAD_REQUEST, NOT_FOUND, etc.)
`message`	string	Human-readable message describing the operation result
`action_time`	string	ISO 8601 timestamp of when the response was generated
`data`	object/string	Response payload for success, error details for failures

HTTP Method Badge Standards

For better visual clarity, all endpoints use colored badges for HTTP methods with the following standard colors:

GET - GET - Green (Safe, read-only operations)
POST - POST - Blue (Create new resources)
PUT - PUT - Yellow (Update/replace entire resource)
PATCH - PATCH - Orange (Partial updates)
DELETE - DELETE - Red (Remove resources)

Endpoints

1. Get My Notifications

Purpose: Retrieves a paginated list of the authenticated user's in-app notifications.

Endpoint: GET {base_url}/notifications/me

Access Level: 🔒 Protected (Authenticated user only)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
`Authorization`	string	Yes	Bearer token for authentication (`Bearer your_token`)

Query Parameters:

Parameter	Type	Required	Description	Validation	Default
`page`	integer	No	Page number for pagination	Min: 1	1
`size`	integer	No	Number of items per page	Min: 1, Max: 100	20

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Notifications retrieved successfully",
  "action_time": "2025-10-18T11:32:00Z",
  "data": {
    "content": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "userId": "223e4567-e89b-12d3-a456-426614174001",
        "shopId": "323e4567-e89b-12d3-a456-426614174002",
        "serviceId": "service-123",
        "serviceType": "ORDER",
        "title": "Order Shipped",
        "message": "Your order has been shipped.",
        "type": "INFO",
        "priority": "NORMAL",
        "isRead": false,
        "data": {
          "orderId": "order-456"
        },
        "createdAt": "2025-10-17T10:00:00Z",
        "readAt": null
      }
    ],
    "pageable": {
      "sort": {
        "sorted": true,
        "unsorted": false,
        "empty": false
      },
      "pageNumber": 0,
      "pageSize": 20,
      "offset": 0,
      "paged": true,
      "unpaged": false
    },
    "totalPages": 1,
    "totalElements": 1,
    "last": true,
    "numberOfElements": 1,
    "first": true,
    "size": 20,
    "number": 0,
    "sort": {
      "sorted": true,
      "unsorted": false,
      "empty": false
    },
    "empty": false
  }
}

Success Response Fields:

Field	Description
`content`	Array of notifications
`content[].id`	Unique identifier of the notification
`content[].userId`	ID of the user receiving the notification
`content[].shopId`	ID of the associated shop (if applicable)
`content[].serviceId`	ID of the service generating the notification
`content[].serviceType`	Type of service (e.g., ORDER)
`content[].title`	Title of the notification
`content[].message`	Body message of the notification
`content[].type`	Type of notification (e.g., INFO)
`content[].priority`	Priority level (e.g., NORMAL)
`content[].isRead`	Whether the notification has been read
`content[].data`	Additional data as key-value pairs
`content[].createdAt`	Timestamp when notification was created
`content[].readAt`	Timestamp when notification was read (null if unread)
`pageable`	Pagination details
`totalPages`	Total number of pages
`totalElements`	Total number of notifications
`last`	Whether this is the last page
`numberOfElements`	Number of elements in this page
`first`	Whether this is the first page
`size`	Page size
`number`	Current page number
`sort`	Sorting details
`empty`	Whether the page is empty

Error Response JSON Sample:

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Invalid pagination parameters",
  "action_time": "2025-10-18T11:32:00Z",
  "data": "Invalid pagination parameters"
}

Standard Error Types:

400 BAD_REQUEST: Invalid pagination parameters
401 UNAUTHORIZED: Invalid or expired token
404 NOT_FOUND: No notifications found

2. Get Unread Notifications

Purpose: Retrieves a paginated list of the authenticated user's unread in-app notifications.

Endpoint: GET {base_url}/notifications/unread

Access Level: 🔒 Protected (Authenticated user only)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
`Authorization`	string	Yes	Bearer token for authentication (`Bearer your_token`)

Query Parameters:

Parameter	Type	Required	Description	Validation	Default
`page`	integer	No	Page number for pagination	Min: 1	1
`size`	integer	No	Number of items per page	Min: 1, Max: 100	20

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Unread notifications retrieved successfully",
  "action_time": "2025-10-18T11:32:00Z",
  "data": {
    "content": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "userId": "223e4567-e89b-12d3-a456-426614174001",
        "shopId": "323e4567-e89b-12d3-a456-426614174002",
        "serviceId": "service-123",
        "serviceType": "ORDER",
        "title": "Order Shipped",
        "message": "Your order has been shipped.",
        "type": "INFO",
        "priority": "NORMAL",
        "isRead": false,
        "data": {
          "orderId": "order-456"
        },
        "createdAt": "2025-10-17T10:00:00Z",
        "readAt": null
      }
    ],
    "pageable": {
      "sort": {
        "sorted": true,
        "unsorted": false,
        "empty": false
      },
      "pageNumber": 0,
      "pageSize": 20,
      "offset": 0,
      "paged": true,
      "unpaged": false
    },
    "totalPages": 1,
    "totalElements": 1,
    "last": true,
    "numberOfElements": 1,
    "first": true,
    "size": 20,
    "number": 0,
    "sort": {
      "sorted": true,
      "unsorted": false,
      "empty": false
    },
    "empty": false
  }
}

Success Response Fields:

Field	Description
`content`	Array of unread notifications (same structure as Get My Notifications)
`pageable`	Pagination details
`totalPages`	Total number of pages
`totalElements`	Total number of unread notifications
`last`	Whether this is the last page
`numberOfElements`	Number of elements in this page
`first`	Whether this is the first page
`size`	Page size
`number`	Current page number
`sort`	Sorting details
`empty`	Whether the page is empty

Error Response JSON Sample:

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Invalid pagination parameters",
  "action_time": "2025-10-18T11:32:00Z",
  "data": "Invalid pagination parameters"
}

Standard Error Types:

400 BAD_REQUEST: Invalid pagination parameters
401 UNAUTHORIZED: Invalid or expired token
404 NOT_FOUND: No unread notifications found

3. Get Notification Summary

Purpose: Retrieves a summary of the authenticated user's notification counts (total, unread, read).

Endpoint: GET {base_url}/notifications/summary

Access Level: 🔒 Protected (Authenticated user only)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
`Authorization`	string	Yes	Bearer token for authentication (`Bearer your_token`)

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Notification summary retrieved successfully",
  "action_time": "2025-10-18T11:32:00Z",
  "data": {
    "totalCount": 10,
    "unreadCount": 3,
    "readCount": 7
  }
}

Success Response Fields:

Field	Description
`totalCount`	Total number of notifications
`unreadCount`	Number of unread notifications
`readCount`	Number of read notifications

Error Response JSON Sample:

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "User ID cannot be null",
  "action_time": "2025-10-18T11:32:00Z",
  "data": "User ID cannot be null"
}

Standard Error Types:

400 BAD_REQUEST: User ID issues
401 UNAUTHORIZED: Invalid or expired token

4. Mark Notification as Read

Purpose: Marks a specific notification as read for the authenticated user.

Endpoint: PATCH {base_url}/notifications/{notificationId}/read

Access Level: 🔒 Protected (Authenticated user only)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
`Authorization`	string	Yes	Bearer token for authentication (`Bearer your_token`)

Path Parameters:

Parameter	Type	Required	Description	Validation
`notificationId`	UUID	Yes	Unique identifier of the notification	Valid UUID format

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Notification marked as read",
  "action_time": "2025-10-18T11:32:00Z",
  "data": null
}

Success Response Fields:

Field	Description
`data`	Null or optional details

Error Response JSON Sample:

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "Notification not found or access denied",
  "action_time": "2025-10-18T11:32:00Z",
  "data": "Notification not found or access denied"
}

Standard Error Types:

400 BAD_REQUEST: Invalid notification ID
401 UNAUTHORIZED: Invalid or expired token
403 FORBIDDEN: Access denied (not user's notification)
404 NOT_FOUND: Notification not found

5. Batch Mark as Read

Purpose: Marks multiple notifications as read for the authenticated user.

Endpoint: PATCH {base_url}/notifications/batch/read

Access Level: 🔒 Protected (Authenticated user only)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
`Authorization`	string	Yes	Bearer token for authentication (`Bearer your_token`)

Request JSON Sample:

{
  "notificationIds": [
    "123e4567-e89b-12d3-a456-426614174000",
    "223e4567-e89b-12d3-a456-426614174001"
  ]
}

Request Body Parameters:

Parameter	Type	Required	Description	Validation
`notificationIds`	array	Yes	List of notification IDs to mark as read	Non-empty array of valid UUIDs

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "2 notification(s) marked as read",
  "action_time": "2025-10-18T11:32:00Z",
  "data": null
}

Success Response Fields:

Field	Description
`data`	Null or optional details

Error Response JSON Sample:

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Notification IDs cannot be empty",
  "action_time": "2025-10-18T11:32:00Z",
  "data": "Notification IDs cannot be empty"
}

Standard Error Types:

400 BAD_REQUEST: Empty or invalid notification IDs
401 UNAUTHORIZED: Invalid or expired token
403 FORBIDDEN: Access denied for some notifications
404 NOT_FOUND: Some notifications not found

6. Mark All as Read

Purpose: Marks all notifications as read for the authenticated user.

Endpoint: PATCH {base_url}/notifications/read

Access Level: 🔒 Protected (Authenticated user only)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
`Authorization`	string	Yes	Bearer token for authentication (`Bearer your_token`)

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "All notifications marked as read",
  "action_time": "2025-10-18T11:32:00Z",
  "data": null
}

Success Response Fields:

Field	Description
`data`	Null or optional details

Error Response JSON Sample:

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "User not found",
  "action_time": "2025-10-18T11:32:00Z",
  "data": "User not found"
}

Standard Error Types:

401 UNAUTHORIZED: Invalid or expired token
404 NOT_FOUND: User not found

7. Delete Notification

Purpose: Deletes a specific notification for the authenticated user.

Endpoint: DELETE {base_url}/notifications/{notificationId}

Access Level: 🔒 Protected (Authenticated user only)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
`Authorization`	string	Yes	Bearer token for authentication (`Bearer your_token`)

Path Parameters:

Parameter	Type	Required	Description	Validation
`notificationId`	UUID	Yes	Unique identifier of the notification	Valid UUID format

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Notification deleted successfully",
  "action_time": "2025-10-18T11:32:00Z",
  "data": null
}

Success Response Fields:

Field	Description
`data`	Null or optional details

Error Response JSON Sample:

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "Notification not found or access denied",
  "action_time": "2025-10-18T11:32:00Z",
  "data": "Notification not found or access denied"
}

Standard Error Types:

400 BAD_REQUEST: Invalid notification ID
401 UNAUTHORIZED: Invalid or expired token
403 FORBIDDEN: Access denied
404 NOT_FOUND: Notification not found

8. Batch Delete Notifications

Purpose: Deletes multiple notifications for the authenticated user.

Endpoint: DELETE {base_url}/notifications/batch

Access Level: 🔒 Protected (Authenticated user only)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
`Authorization`	string	Yes	Bearer token for authentication (`Bearer your_token`)

Request JSON Sample:

{
  "notificationIds": [
    "123e4567-e89b-12d3-a456-426614174000",
    "223e4567-e89b-12d3-a456-426614174001"
  ]
}

Request Body Parameters:

Parameter	Type	Required	Description	Validation
`notificationIds`	array	Yes	List of notification IDs to delete	Non-empty array of valid UUIDs

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "2 notification(s) deleted successfully",
  "action_time": "2025-10-18T11:32:00Z",
  "data": null
}

Success Response Fields:

Field	Description
`data`	Null or optional details

Error Response JSON Sample:

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Notification IDs cannot be empty",
  "action_time": "2025-10-18T11:32:00Z",
  "data": "Notification IDs cannot be empty"
}

Standard Error Types:

400 BAD_REQUEST: Empty or invalid notification IDs
401 UNAUTHORIZED: Invalid or expired token
403 FORBIDDEN: Access denied for some notifications
404 NOT_FOUND: Some notifications not found

9. Delete All Read Notifications

Purpose: Deletes all read notifications for the authenticated user.

Endpoint: DELETE {base_url}/notifications/read

Access Level: 🔒 Protected (Authenticated user only)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
`Authorization`	string	Yes	Bearer token for authentication (`Bearer your_token`)

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "5 read notification(s) deleted successfully",
  "action_time": "2025-10-18T11:32:00Z",
  "data": 5
}

Success Response Fields:

Field	Description
`data`	Number of deleted notifications

Error Response JSON Sample:

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "User ID cannot be null",
  "action_time": "2025-10-18T11:32:00Z",
  "data": "User ID cannot be null"
}

Standard Error Types:

400 BAD_REQUEST: User ID issues
401 UNAUTHORIZED: Invalid or expired token

Quick Reference Guide

HTTP Method Badge Code Templates

GET Badge:

<span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span>

POST Badge:

<span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span>

PATCH Badge:

<span style="background-color: #fd7e14; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">PATCH</span>

DELETE Badge:

<span style="background-color: #dc3545; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">DELETE</span>

Common HTTP Status Codes

200 OK: Successful GET/PUT/PATCH request
201 Created: Successful POST request
204 No Content: Successful DELETE request
400 Bad Request: Invalid request data
401 Unauthorized: Authentication required/failed
403 Forbidden: Insufficient permissions
404 Not Found: Resource not found
422 Unprocessable Entity: Validation errors
429 Too Many Requests: Rate limit exceeded
500 Internal Server Error: Server error

Authentication Types

Bearer Token: Include Authorization: Bearer your_token in headers

Data Format Standards

Dates: Use ISO 8601 format (2025-10-18T11:32:00Z)
IDs: UUID format
Pagination: Include page, size, total_count, total_pages