refactor(deprecation): add deprecated route handling for /blacklist endpoint

Author: fallenbagel

seerr-api.yml

@@ -4638,6 +4638,126 @@ paths:
       responses:
         '204':
           description: Succesfully removed media item
+  /blacklist:
+    get:
+      summary: Returns blocklisted items
+      description: |
+        **DEPRECATED**: Use `/blocklist` instead. This endpoint will be deprecated soon.
+      deprecated: true
+      tags:
+        - blocklist
+      parameters:
+        - in: query
+          name: take
+          schema:
+            type: number
+            nullable: true
+            example: 25
+        - in: query
+          name: skip
+          schema:
+            type: number
+            nullable: true
+            example: 0
+        - in: query
+          name: search
+          schema:
+            type: string
+            nullable: true
+            example: dune
+        - in: query
+          name: filter
+          schema:
+            type: string
+            enum: [all, manual, blocklistedTags]
+            default: manual
+      responses:
+        '200':
+          description: Blocklisted items returned
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  pageInfo:
+                    $ref: '#/components/schemas/PageInfo'
+                  results:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        user:
+                          $ref: '#/components/schemas/User'
+                        createdAt:
+                          type: string
+                          example: 2024-04-21T01:55:44.000Z
+                        id:
+                          type: number
+                          example: 1
+                        mediaType:
+                          type: string
+                          example: movie
+                        title:
+                          type: string
+                          example: Dune
+                        tmdbId:
+                          type: number
+                          example: 438631
+    post:
+      summary: Add media to blocklist
+      description: |
+        **DEPRECATED**: Use `/blocklist` instead. This endpoint will be deprecated soon.
+      deprecated: true
+      tags:
+        - blocklist
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Blocklist'
+      responses:
+        '201':
+          description: Item succesfully blocklisted
+        '412':
+          description: Item has already been blocklisted
+  /blacklist/{tmdbId}:
+    get:
+      summary: Get media from blocklist
+      description: |
+        **DEPRECATED**: Use `/blocklist/{tmdbId}` instead. This endpoint will be deprecated soon.
+      deprecated: true
+      tags:
+        - blocklist
+      parameters:
+        - in: path
+          name: tmdbId
+          description: tmdbId ID
+          required: true
+          example: '1'
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Blocklist details in JSON
+    delete:
+      summary: Remove media from blocklist
+      description: |
+        **DEPRECATED**: Use `/blocklist/{tmdbId}` instead. This endpoint will be deprecated soon.
+      deprecated: true
+      tags:
+        - blocklist
+      parameters:
+        - in: path
+          name: tmdbId
+          description: tmdbId ID
+          required: true
+          example: '1'
+          schema:
+            type: string
+      responses:
+        '204':
+          description: Succesfully removed media item
   /watchlist:
     post:
       summary: Add media to watchlist

server/middleware/deprecation.ts

@@ -0,0 +1,49 @@
+import logger from '@server/logger';
+import type { NextFunction, Request, Response } from 'express';
+
+interface DeprecationOptions {
+  oldPath: string;
+  newPath: string;
+  sunsetDate?: string;
+  documentationUrl?: string;
+}
+
+/**
+ * Mark an API route as deprecated.
+ * @see https://datatracker.ietf.org/doc/html/rfc8594
+ */
+export const deprecatedRoute = ({
+  oldPath,
+  newPath,
+  sunsetDate,
+  documentationUrl,
+}: DeprecationOptions) => {
+  return (req: Request, res: Response, next: NextFunction) => {
+    logger.warn(
+      `Deprecated API endpoint accessed: ${oldPath} → use ${newPath} instead`,
+      {
+        label: 'API Deprecation',
+        ip: req.ip,
+        userAgent: req.get('User-Agent'),
+        method: req.method,
+        path: req.originalUrl,
+      }
+    );
+
+    res.setHeader('Deprecation', 'true');
+
+    const links: string[] = [`<${newPath}>; rel="successor-version"`];
+    if (documentationUrl) {
+      links.push(`<${documentationUrl}>; rel="deprecation"`);
+    }
+    res.setHeader('Link', links.join(', '));
+
+    if (sunsetDate) {
+      res.setHeader('Sunset', new Date(sunsetDate).toUTCString());
+    }
+
+    next();
+  };
+};
+
+export default deprecatedRoute;

server/routes/index.ts

@@ -12,6 +12,7 @@ import { Permission } from '@server/lib/permissions';
 import { getSettings } from '@server/lib/settings';
 import logger from '@server/logger';
 import { checkUser, isAuthenticated } from '@server/middleware/auth';
+import deprecatedRoute from '@server/middleware/deprecation';
 import { mapWatchProviderDetails } from '@server/models/common';
 import { mapProductionCompany } from '@server/models/Movie';
 import { mapNetwork } from '@server/models/Tv';
@@ -152,6 +153,16 @@ router.use('/discover', isAuthenticated(), discoverRoutes);
 router.use('/request', isAuthenticated(), requestRoutes);
 router.use('/watchlist', isAuthenticated(), watchlistRoutes);
 router.use('/blocklist', isAuthenticated(), blocklistRoutes);
+router.use(
+  '/blacklist',
+  isAuthenticated(),
+  deprecatedRoute({
+    oldPath: '/api/v1/blacklist',
+    newPath: '/api/v1/blocklist',
+    sunsetDate: '2025-06-01',
+  }),
+  blocklistRoutes
+);
 router.use('/movie', isAuthenticated(), movieRoutes);
 router.use('/tv', isAuthenticated(), tvRoutes);
 router.use('/media', isAuthenticated(), mediaRoutes);