[Notifications] REST API endpoints (#3580210) · Issues · project / canvas

[Notifications] REST API endpoints

>>> [!note] Migrated issue   Reported by: [justafish](https://www.drupal.org/user/161058) Related to !829 >>> Create the REST API controller and routes that expose the notification system to the Canvas UI. Two endpoints are needed: one to fetch recent notifications (with per-user read state), and one to mark notifications as read. <h2>Dependencies</h2> Ticket 1 (notification storage and service) must be complete. <h2>Acceptance criteria</h2> <ul> <li><code>GET /canvas/api/v0/notifications</code> returns recent notifications with <code>hasRead</code> per authenticated user.</li> <li><code>POST /canvas/api/v0/notifications/read</code> accepts <code>{ "ids": ["uuid", ...] }</code> and marks those notifications as read for the current user.</li> <li>POST returns <code>204 No Content</code> on success.</li> <li>POST returns <code>400 Bad Request</code> if the body is empty or <code>ids</code> is missing.</li> <li>Both routes require <code>_canvas_authentication_required: TRUE</code> and <code>_canvas_ui_access: 'TRUE'</code>.</li> <li>Routes are added to <code>canvas.routing.yml</code>.</li> <li>Controller is registered in <code>canvas.services.yml</code>.</li> <li>OpenAPI spec (<code>openapi.yml</code>) is updated with both endpoint definitions.</li> <li>Integration tests validate response shapes, status codes, and access control.</li> </ul> <h2>Implementation plan</h2> <h3>Routes</h3> Add to <code>canvas.routing.yml</code>: <pre><pre>canvas.api.notifications.get:   path: '/canvas/api/v0/notifications'   defaults:     _controller: 'Drupal\canvas\Controller\ApiNotificationController::list'   requirements:     _canvas_authentication_required: TRUE     _canvas_ui_access: 'TRUE'   methods: ['GET']   options:     _format: 'json' canvas.api.notifications.read:   path: '/canvas/api/v0/notifications/read'   defaults:     _controller: 'Drupal\canvas\Controller\ApiNotificationController::markRead'   requirements:     _canvas_authentication_required: TRUE     _canvas_ui_access: 'TRUE'   methods: ['POST']   options:     _format: 'json'</pre></pre><h3>Controller</h3> Create <code>src/Controller/ApiNotificationController.php</code>: <pre><pre>&lt;?php declare(strict_types=1); namespace Drupal\canvas\Controller; use Drupal\canvas\Notification\NotificationService; use Drupal\Core\Session\AccountProxyInterface; use Symfony\Component\HttpFoundation\JsonResponse; use Symfony\Component\HttpFoundation\Request; use Symfony\Component\HttpFoundation\Response; final class ApiNotificationController extends ApiControllerBase {   public function __construct(     private readonly NotificationService $notificationService,     private readonly AccountProxyInterface $currentUser,   ) {}   public function list(): JsonResponse {     $uid = (int) $this->currentUser->id();     $notifications = $this->notificationService->getRecent($uid);     return new JsonResponse([       'data' => [         'notifications' => $notifications,       ],     ]);   }   public function markRead(Request $request): Response {     $data = static::decode($request);     if (!isset($data['ids']) || !is_array($data['ids'])) {       throw new \Symfony\Component\HttpKernel\Exception\BadRequestHttpException(         'Missing or invalid "ids" field.'       );     }     $uid = (int) $this->currentUser->id();     $this->notificationService->markRead($uid, $data['ids']);     return new Response('', 204);   } }</pre></pre><h3>Service registration</h3> Add to <code>canvas.services.yml</code>: <pre>Drupal\canvas\Controller\ApiNotificationController: {}</pre><h3>OpenAPI spec</h3> Add to <code>openapi.yml</code> under <code>paths</code>: <pre><pre>/canvas/api/v0/notifications:   get:     summary: Fetch recent notifications for the authenticated user.     responses:       '200':         description: List of recent notifications.         content:           application/json:             schema:               type: object               required: [data]               properties:                 data:                   type: object                   required: [notifications]                   properties:                     notifications:                       type: array                       items:                         $ref: '#/components/schemas/Notification'       '403':         $ref: '#/components/responses/ClientErrorResponse' /canvas/api/v0/notifications/read:   post:     summary: Mark notifications as read for the authenticated user.     requestBody:       required: true       content:         application/json:           schema:             type: object             required: [ids]             properties:               ids:                 type: array                 items:                   type: string                   format: uuid     responses:       '204':         description: Notifications marked as read.       '400':         $ref: '#/components/responses/ClientErrorResponse'       '403':         $ref: '#/components/responses/ClientErrorResponse'</pre></pre>Add to <code>components/schemas</code>: <pre><pre>Notification:   type: object   required: [id, type, title, message, timestamp, hasRead]   properties:     id:       type: string       format: uuid     type:       type: string       enum: [processing, success, info, warning, error]     key:       type: string       nullable: true     title:       type: string     message:       type: string     timestamp:       type: integer       description: Unix timestamp in milliseconds.     hasRead:       type: boolean     actions:       type: array       nullable: true       items:         type: object         required: [label, href]         properties:           label:             type: string           href:             type: string</pre></pre><h3>GET response shape</h3> <pre><pre>{   "data": {     "notifications": [       {         "id": "550e8400-e29b-41d4-a716-446655440000",         "type": "processing",         "key": "github_sync",         "title": "Sync in progress",         "message": "Syncing with GitHub repository...",         "timestamp": 1234567890000,         "hasRead": false,         "actions": null       },       {         "id": "550e8400-e29b-41d4-a716-446655440001",         "type": "error",         "key": "github_sync",         "title": "Publish failed",         "message": "Unable to connect to server",         "timestamp": 1234567880000,         "hasRead": true,         "actions": [           { "label": "View logs", "href": "/logs" },           { "label": "Revert", "href": "/github-revert" }         ]       }     ]   } }</pre></pre><h3>POST /notifications/read request shape</h3> <pre><pre>{   "ids": [     "550e8400-e29b-41d4-a716-446655440001",     "550e8400-e29b-41d4-a716-446655440002"   ] }</pre></pre><h2>Tests required</h2> Kernel test: <code>tests/src/Kernel/Controller/ApiNotificationControllerTest.php</code> Follow existing Canvas kernel test patterns. Use <code>RequestTrait</code> for simulating HTTP requests. <table> <thead> <tr> <th>Test method</th> <th>Validates</th> </tr> </thead> <tbody> <tr> <td><code>testGetNotificationsReturnsJsonResponse</code></td> <td>200 with correct response shape</td> </tr> <tr> <td><code>testGetNotificationsIncludesHasReadPerUser</code></td> <td><code>hasRead</code> differs per user</td> </tr> <tr> <td><code>testGetNotificationsRequiresAuthentication</code></td> <td>Anonymous user gets 401</td> </tr> <tr> <td><code>testMarkReadReturns204</code></td> <td>Successful mark-read returns 204</td> </tr> <tr> <td><code>testMarkReadUpdatesHasRead</code></td> <td>Subsequent GET shows <code>hasRead: true</code></td> </tr> <tr> <td><code>testMarkReadRejectsMissingIds</code></td> <td>Missing <code>ids</code> field returns 400</td> </tr> <tr> <td><code>testMarkReadRejectsEmptyBody</code></td> <td>Empty body returns 400</td> </tr> </tbody> </table> Use the existing <code>OpenApiSpecTrait</code> to validate that responses match the spec. <h2>Manual testing steps</h2> <ol> <li>Ensure <code>canvas_dev_mode</code> is enabled and the <code>canvas_notifications</code> / <code>canvas_notification_reads</code> tables exist: <pre>ddev drush sqlq "SHOW TABLES LIKE 'canvas_notif%';"</pre></li> <li>Create test notifications via Drush (see ticket 1 manual steps).</li> <li>Open the Canvas UI and use the browser network tab to call the GET endpoint directly. Verify the response includes a <code>notifications</code> array.</li> <li> Copy a notification ID from the response and mark it as read: <pre><pre>POST /canvas/api/v0/notifications/read Content-Type: application/json { "ids": ["&lt;notification-id&gt;"] }</pre></pre>Verify the response is <code>204 No Content</code>. </li> <li>Call GET again and verify <code>hasRead</code> is now <code>true</code> for that notification.</li> <li>Open a second browser / incognito window with a different user. Verify that the same notification shows <code>hasRead: false</code> for the other user.</li> <li>Test access control: log out and call GET — expect 401.</li> </ol>

issue