refactor(server): deprecate PUT routes in favor of PATCH (#28859)

* add patch routes and deprecate put

* gen client

server/src/controllers/api-key.controller.ts

@@ -1,5 +1,5 @@
-import { Body, Controller, Delete, Get, HttpCode, HttpStatus, Param, Post, Put } from '@nestjs/common';
-import { ApiTags } from '@nestjs/swagger';
+import { Body, Controller, Delete, Get, HttpCode, HttpStatus, Param, Patch, Post, Put } from '@nestjs/common';
+import { ApiExcludeEndpoint, ApiTags } from '@nestjs/swagger';
 import { Endpoint, HistoryBuilder } from 'src/decorators';
 import { ApiKeyCreateDto, ApiKeyCreateResponseDto, ApiKeyResponseDto, ApiKeyUpdateDto } from 'src/dtos/api-key.dto';
 import { AuthDto } from 'src/dtos/auth.dto';
@@ -62,7 +62,11 @@ export class ApiKeyController {
   @Endpoint({
     summary: 'Update an API key',
     description: 'Updates the name and permissions of an API key by its ID. The current user must own this API key.',
-    history: new HistoryBuilder().added('v1').beta('v1').stable('v2'),
+    history: new HistoryBuilder()
+      .added('v1')
+      .beta('v1')
+      .stable('v2')
+      .deprecated('v3', { replacementId: 'updateApiKey' }),
   })
   updateApiKey(
     @Auth() auth: AuthDto,
@@ -72,6 +76,17 @@ export class ApiKeyController {
     return this.service.update(auth, id, dto);
   }
 
+  @Patch(':id')
+  @ApiExcludeEndpoint()
+  @Authenticated({ permission: Permission.ApiKeyUpdate })
+  updateApiKeyV3(
+    @Auth() auth: AuthDto,
+    @Param() { id }: UUIDParamDto,
+    @Body() dto: ApiKeyUpdateDto,
+  ): Promise<ApiKeyResponseDto> {
+    return this.service.update(auth, id, dto);
+  }
+
   @Delete(':id')
   @Authenticated({ permission: Permission.ApiKeyDelete })
   @HttpCode(HttpStatus.NO_CONTENT)

server/src/controllers/asset.controller.ts

@@ -1,5 +1,5 @@
-import { Body, Controller, Delete, Get, HttpCode, HttpStatus, Param, Post, Put, Query } from '@nestjs/common';
-import { ApiTags } from '@nestjs/swagger';
+import { Body, Controller, Delete, Get, HttpCode, HttpStatus, Param, Patch, Post, Put, Query } from '@nestjs/common';
+import { ApiExcludeEndpoint, ApiTags } from '@nestjs/swagger';
 import { Endpoint, HistoryBuilder } from 'src/decorators';
 import { AssetResponseDto } from 'src/dtos/asset-response.dto';
 import {
@@ -59,12 +59,24 @@ export class AssetController {
   @Endpoint({
     summary: 'Update assets',
     description: 'Updates multiple assets at the same time.',
-    history: new HistoryBuilder().added('v1').beta('v1').stable('v2'),
+    history: new HistoryBuilder()
+      .added('v1')
+      .beta('v1')
+      .stable('v2')
+      .deprecated('v3', { replacementId: 'updateAssets' }),
   })
   updateAssets(@Auth() auth: AuthDto, @Body() dto: AssetBulkUpdateDto): Promise<void> {
     return this.service.updateAll(auth, dto);
   }
 
+  @Patch()
+  @ApiExcludeEndpoint()
+  @Authenticated({ permission: Permission.AssetUpdate })
+  @HttpCode(HttpStatus.NO_CONTENT)
+  updateAssetsV3(@Auth() auth: AuthDto, @Body() dto: AssetBulkUpdateDto): Promise<void> {
+    return this.service.updateAll(auth, dto);
+  }
+
   @Delete()
   @Authenticated({ permission: Permission.AssetDelete })
   @HttpCode(HttpStatus.NO_CONTENT)
@@ -131,7 +143,11 @@ export class AssetController {
   @Endpoint({
     summary: 'Update an asset',
     description: 'Update information of a specific asset.',
-    history: new HistoryBuilder().added('v1').beta('v1').stable('v2'),
+    history: new HistoryBuilder()
+      .added('v1')
+      .beta('v1')
+      .stable('v2')
+      .deprecated('v3', { replacementId: 'updateAsset' }),
   })
   updateAsset(
     @Auth() auth: AuthDto,
@@ -141,6 +157,17 @@ export class AssetController {
     return this.service.update(auth, id, dto);
   }
 
+  @Patch(':id')
+  @ApiExcludeEndpoint()
+  @Authenticated({ permission: Permission.AssetUpdate })
+  updateAssetV3(
+    @Auth() auth: AuthDto,
+    @Param() { id }: UUIDParamDto,
+    @Body() dto: UpdateAssetDto,
+  ): Promise<AssetResponseDto> {
+    return this.service.update(auth, id, dto);
+  }
+
   @Get(':id/metadata')
   @Authenticated({ permission: Permission.AssetRead })
   @Endpoint({

server/src/controllers/library.controller.ts

@@ -1,5 +1,5 @@
-import { Body, Controller, Delete, Get, HttpCode, HttpStatus, Param, Post, Put } from '@nestjs/common';
-import { ApiTags } from '@nestjs/swagger';
+import { Body, Controller, Delete, Get, HttpCode, HttpStatus, Param, Patch, Post, Put } from '@nestjs/common';
+import { ApiExcludeEndpoint, ApiTags } from '@nestjs/swagger';
 import { Endpoint, HistoryBuilder } from 'src/decorators';
 import {
   CreateLibraryDto,
@@ -57,12 +57,23 @@ export class LibraryController {
   @Endpoint({
     summary: 'Update a library',
     description: 'Update an existing external library.',
-    history: new HistoryBuilder().added('v1').beta('v1').stable('v2'),
+    history: new HistoryBuilder()
+      .added('v1')
+      .beta('v1')
+      .stable('v2')
+      .deprecated('v3', { replacementId: 'updateLibrary' }),
   })
   updateLibrary(@Param() { id }: UUIDParamDto, @Body() dto: UpdateLibraryDto): Promise<LibraryResponseDto> {
     return this.service.update(id, dto);
   }
 
+  @Patch(':id')
+  @ApiExcludeEndpoint()
+  @Authenticated({ permission: Permission.LibraryUpdate, admin: true })
+  updateLibraryV3(@Param() { id }: UUIDParamDto, @Body() dto: UpdateLibraryDto): Promise<LibraryResponseDto> {
+    return this.service.update(id, dto);
+  }
+
   @Delete(':id')
   @Authenticated({ permission: Permission.LibraryDelete, admin: true })
   @HttpCode(HttpStatus.NO_CONTENT)

server/src/controllers/memory.controller.ts

@@ -1,5 +1,5 @@
-import { Body, Controller, Delete, Get, HttpCode, HttpStatus, Param, Post, Put, Query } from '@nestjs/common';
-import { ApiTags } from '@nestjs/swagger';
+import { Body, Controller, Delete, Get, HttpCode, HttpStatus, Param, Patch, Post, Put, Query } from '@nestjs/common';
+import { ApiExcludeEndpoint, ApiTags } from '@nestjs/swagger';
 import { Endpoint, HistoryBuilder } from 'src/decorators';
 import { BulkIdResponseDto, BulkIdsDto } from 'src/dtos/asset-ids.response.dto';
 import { AuthDto } from 'src/dtos/auth.dto';
@@ -71,7 +71,11 @@ export class MemoryController {
   @Endpoint({
     summary: 'Update a memory',
     description: 'Update an existing memory by its ID.',
-    history: new HistoryBuilder().added('v1').beta('v1').stable('v2'),
+    history: new HistoryBuilder()
+      .added('v1')
+      .beta('v1')
+      .stable('v2')
+      .deprecated('v3', { replacementId: 'updateMemory' }),
   })
   updateMemory(
     @Auth() auth: AuthDto,
@@ -81,6 +85,17 @@ export class MemoryController {
     return this.service.update(auth, id, dto);
   }
 
+  @Patch(':id')
+  @ApiExcludeEndpoint()
+  @Authenticated({ permission: Permission.MemoryUpdate })
+  updateMemoryV3(
+    @Auth() auth: AuthDto,
+    @Param() { id }: UUIDParamDto,
+    @Body() dto: MemoryUpdateDto,
+  ): Promise<MemoryResponseDto> {
+    return this.service.update(auth, id, dto);
+  }
+
   @Delete(':id')
   @Authenticated({ permission: Permission.MemoryDelete })
   @HttpCode(HttpStatus.NO_CONTENT)

server/src/controllers/person.controller.ts

@@ -7,12 +7,13 @@ import {
   HttpStatus,
   Next,
   Param,
+  Patch,
   Post,
   Put,
   Query,
   Res,
 } from '@nestjs/common';
-import { ApiTags } from '@nestjs/swagger';
+import { ApiExcludeEndpoint, ApiTags } from '@nestjs/swagger';
 import { NextFunction, Response } from 'express';
 import { Endpoint, HistoryBuilder } from 'src/decorators';
 import { BulkIdResponseDto, BulkIdsDto } from 'src/dtos/asset-ids.response.dto';
@@ -106,7 +107,11 @@ export class PersonController {
   @Endpoint({
     summary: 'Update person',
     description: 'Update an individual person.',
-    history: new HistoryBuilder().added('v1').beta('v1').stable('v2'),
+    history: new HistoryBuilder()
+      .added('v1')
+      .beta('v1')
+      .stable('v2')
+      .deprecated('v3', { replacementId: 'updatePerson' }),
   })
   updatePerson(
     @Auth() auth: AuthDto,
@@ -116,6 +121,17 @@ export class PersonController {
     return this.service.update(auth, id, dto);
   }
 
+  @Patch(':id')
+  @ApiExcludeEndpoint()
+  @Authenticated({ permission: Permission.PersonUpdate })
+  updatePersonV3(
+    @Auth() auth: AuthDto,
+    @Param() { id }: UUIDParamDto,
+    @Body() dto: PersonUpdateDto,
+  ): Promise<PersonResponseDto> {
+    return this.service.update(auth, id, dto);
+  }
+
   @Delete(':id')
   @Authenticated({ permission: Permission.PersonDelete })
   @HttpCode(HttpStatus.NO_CONTENT)

server/src/controllers/session.controller.ts

@@ -1,5 +1,5 @@
-import { Body, Controller, Delete, Get, HttpCode, HttpStatus, Param, Post, Put } from '@nestjs/common';
-import { ApiTags } from '@nestjs/swagger';
+import { Body, Controller, Delete, Get, HttpCode, HttpStatus, Param, Patch, Post, Put } from '@nestjs/common';
+import { ApiExcludeEndpoint, ApiTags } from '@nestjs/swagger';
 import { Endpoint, HistoryBuilder } from 'src/decorators';
 import { AuthDto } from 'src/dtos/auth.dto';
 import { SessionCreateDto, SessionCreateResponseDto, SessionResponseDto, SessionUpdateDto } from 'src/dtos/session.dto';
@@ -52,7 +52,11 @@ export class SessionController {
   @Endpoint({
     summary: 'Update a session',
     description: 'Update a specific session identified by id.',
-    history: new HistoryBuilder().added('v1').beta('v1').stable('v2'),
+    history: new HistoryBuilder()
+      .added('v1')
+      .beta('v1')
+      .stable('v2')
+      .deprecated('v3', { replacementId: 'updateSession' }),
   })
   updateSession(
     @Auth() auth: AuthDto,
@@ -62,6 +66,17 @@ export class SessionController {
     return this.service.update(auth, id, dto);
   }
 
+  @Patch(':id')
+  @ApiExcludeEndpoint()
+  @Authenticated({ permission: Permission.SessionUpdate })
+  updateSessionV3(
+    @Auth() auth: AuthDto,
+    @Param() { id }: UUIDParamDto,
+    @Body() dto: SessionUpdateDto,
+  ): Promise<SessionResponseDto> {
+    return this.service.update(auth, id, dto);
+  }
+
   @Delete(':id')
   @Authenticated({ permission: Permission.SessionDelete })
   @HttpCode(HttpStatus.NO_CONTENT)

server/src/controllers/stack.controller.ts

@@ -1,5 +1,5 @@
-import { Body, Controller, Delete, Get, HttpCode, HttpStatus, Param, Post, Put, Query } from '@nestjs/common';
-import { ApiTags } from '@nestjs/swagger';
+import { Body, Controller, Delete, Get, HttpCode, HttpStatus, Param, Patch, Post, Put, Query } from '@nestjs/common';
+import { ApiExcludeEndpoint, ApiTags } from '@nestjs/swagger';
 import { Endpoint, HistoryBuilder } from 'src/decorators';
 import { BulkIdsDto } from 'src/dtos/asset-ids.response.dto';
 import { AuthDto } from 'src/dtos/auth.dto';
@@ -65,7 +65,11 @@ export class StackController {
   @Endpoint({
     summary: 'Update a stack',
     description: 'Update an existing stack by its ID.',
-    history: new HistoryBuilder().added('v1').beta('v1').stable('v2'),
+    history: new HistoryBuilder()
+      .added('v1')
+      .beta('v1')
+      .stable('v2')
+      .deprecated('v3', { replacementId: 'updateStack' }),
   })
   updateStack(
     @Auth() auth: AuthDto,
@@ -75,6 +79,17 @@ export class StackController {
     return this.service.update(auth, id, dto);
   }
 
+  @Patch(':id')
+  @ApiExcludeEndpoint()
+  @Authenticated({ permission: Permission.StackUpdate })
+  updateStackV3(
+    @Auth() auth: AuthDto,
+    @Param() { id }: UUIDParamDto,
+    @Body() dto: StackUpdateDto,
+  ): Promise<StackResponseDto> {
+    return this.service.update(auth, id, dto);
+  }
+
   @Delete(':id')
   @Authenticated({ permission: Permission.StackDelete })
   @HttpCode(HttpStatus.NO_CONTENT)

server/src/controllers/tag.controller.ts

@@ -1,5 +1,5 @@
-import { Body, Controller, Delete, Get, HttpCode, HttpStatus, Param, Post, Put } from '@nestjs/common';
-import { ApiTags } from '@nestjs/swagger';
+import { Body, Controller, Delete, Get, HttpCode, HttpStatus, Param, Patch, Post, Put } from '@nestjs/common';
+import { ApiExcludeEndpoint, ApiTags } from '@nestjs/swagger';
 import { Endpoint, HistoryBuilder } from 'src/decorators';
 import { BulkIdResponseDto, BulkIdsDto } from 'src/dtos/asset-ids.response.dto';
 import { AuthDto } from 'src/dtos/auth.dto';
@@ -81,12 +81,23 @@ export class TagController {
   @Endpoint({
     summary: 'Update a tag',
     description: 'Update an existing tag identified by its ID.',
-    history: new HistoryBuilder().added('v1').beta('v1').stable('v2'),
+    history: new HistoryBuilder().added('v1').beta('v1').stable('v2').deprecated('v3', { replacementId: 'updateTag' }),
   })
   updateTag(@Auth() auth: AuthDto, @Param() { id }: UUIDParamDto, @Body() dto: TagUpdateDto): Promise<TagResponseDto> {
     return this.service.update(auth, id, dto);
   }
 
+  @Patch(':id')
+  @ApiExcludeEndpoint()
+  @Authenticated({ permission: Permission.TagUpdate })
+  updateTagV3(
+    @Auth() auth: AuthDto,
+    @Param() { id }: UUIDParamDto,
+    @Body() dto: TagUpdateDto,
+  ): Promise<TagResponseDto> {
+    return this.service.update(auth, id, dto);
+  }
+
   @Delete(':id')
   @Authenticated({ permission: Permission.TagDelete })
   @HttpCode(HttpStatus.NO_CONTENT)

server/src/controllers/user-admin.controller.ts

@@ -1,5 +1,5 @@
-import { Body, Controller, Delete, Get, HttpCode, HttpStatus, Param, Post, Put, Query } from '@nestjs/common';
-import { ApiTags } from '@nestjs/swagger';
+import { Body, Controller, Delete, Get, HttpCode, HttpStatus, Param, Patch, Post, Put, Query } from '@nestjs/common';
+import { ApiExcludeEndpoint, ApiTags } from '@nestjs/swagger';
 import { Endpoint, HistoryBuilder } from 'src/decorators';
 import { AssetStatsDto, AssetStatsResponseDto } from 'src/dtos/asset.dto';
 import { AuthDto } from 'src/dtos/auth.dto';
@@ -61,7 +61,11 @@ export class UserAdminController {
   @Endpoint({
     summary: 'Update a user',
     description: 'Update an existing user.',
-    history: new HistoryBuilder().added('v1').beta('v1').stable('v2'),
+    history: new HistoryBuilder()
+      .added('v1')
+      .beta('v1')
+      .stable('v2')
+      .deprecated('v3', { replacementId: 'updateUserAdmin' }),
   })
   updateUserAdmin(
     @Auth() auth: AuthDto,
@@ -71,6 +75,17 @@ export class UserAdminController {
     return this.service.update(auth, id, dto);
   }
 
+  @Patch(':id')
+  @ApiExcludeEndpoint()
+  @Authenticated({ permission: Permission.AdminUserUpdate, admin: true })
+  updateUserAdminV3(
+    @Auth() auth: AuthDto,
+    @Param() { id }: UUIDParamDto,
+    @Body() dto: UserAdminUpdateDto,
+  ): Promise<UserAdminResponseDto> {
+    return this.service.update(auth, id, dto);
+  }
+
   @Delete(':id')
   @Authenticated({ permission: Permission.AdminUserDelete, admin: true })
   @Endpoint({
@@ -143,7 +158,11 @@ export class UserAdminController {
   @Endpoint({
     summary: 'Update user preferences',
     description: 'Update the preferences of a specific user.',
-    history: new HistoryBuilder().added('v1').beta('v1').stable('v2'),
+    history: new HistoryBuilder()
+      .added('v1')
+      .beta('v1')
+      .stable('v2')
+      .deprecated('v3', { replacementId: 'updateUserPreferencesAdmin' }),
   })
   updateUserPreferencesAdmin(
     @Auth() auth: AuthDto,
@@ -153,6 +172,17 @@ export class UserAdminController {
     return this.service.updatePreferences(auth, id, dto);
   }
 
+  @Patch(':id/preferences')
+  @ApiExcludeEndpoint()
+  @Authenticated({ permission: Permission.AdminUserUpdate, admin: true })
+  updateUserPreferencesAdminV3(
+    @Auth() auth: AuthDto,
+    @Param() { id }: UUIDParamDto,
+    @Body() dto: UserPreferencesUpdateDto,
+  ): Promise<UserPreferencesResponseDto> {
+    return this.service.updatePreferences(auth, id, dto);
+  }
+
   @Post(':id/restore')
   @Authenticated({ permission: Permission.AdminUserDelete, admin: true })
   @HttpCode(HttpStatus.OK)

server/src/controllers/user.controller.ts

@@ -7,6 +7,7 @@ import {
   HttpStatus,
   Next,
   Param,
+  Patch,
   Post,
   Put,
   Query,
@@ -14,7 +15,7 @@ import {
   UploadedFile,
   UseInterceptors,
 } from '@nestjs/common';
-import { ApiBody, ApiConsumes, ApiTags } from '@nestjs/swagger';
+import { ApiBody, ApiConsumes, ApiExcludeEndpoint, ApiTags } from '@nestjs/swagger';
 import { NextFunction, Response } from 'express';
 import { Endpoint, HistoryBuilder } from 'src/decorators';
 import { AuthDto } from 'src/dtos/auth.dto';
@@ -78,12 +79,23 @@ export class UserController {
   @Endpoint({
     summary: 'Update current user',
     description: 'Update the current user making the API request.',
-    history: new HistoryBuilder().added('v1').beta('v1').stable('v2'),
+    history: new HistoryBuilder()
+      .added('v1')
+      .beta('v1')
+      .stable('v2')
+      .deprecated('v3', { replacementId: 'updateMyUser' }),
   })
   updateMyUser(@Auth() auth: AuthDto, @Body() dto: UserUpdateMeDto): Promise<UserAdminResponseDto> {
     return this.service.updateMe(auth, dto);
   }
 
+  @Patch('me')
+  @ApiExcludeEndpoint()
+  @Authenticated({ permission: Permission.UserUpdate })
+  updateMyUserV3(@Auth() auth: AuthDto, @Body() dto: UserUpdateMeDto): Promise<UserAdminResponseDto> {
+    return this.service.updateMe(auth, dto);
+  }
+
   @Get('me/preferences')
   @Authenticated({ permission: Permission.UserPreferenceRead })
   @Endpoint({
@@ -100,7 +112,11 @@ export class UserController {
   @Endpoint({
     summary: 'Update my preferences',
     description: 'Update the preferences of the current user.',
-    history: new HistoryBuilder().added('v1').beta('v1').stable('v2'),
+    history: new HistoryBuilder()
+      .added('v1')
+      .beta('v1')
+      .stable('v2')
+      .deprecated('v3', { replacementId: 'updateMyPreferences' }),
   })
   updateMyPreferences(
     @Auth() auth: AuthDto,
@@ -109,6 +125,16 @@ export class UserController {
     return this.service.updateMyPreferences(auth, dto);
   }
 
+  @Patch('me/preferences')
+  @ApiExcludeEndpoint()
+  @Authenticated({ permission: Permission.UserPreferenceUpdate })
+  updateMyPreferencesV3(
+    @Auth() auth: AuthDto,
+    @Body() dto: UserPreferencesUpdateDto,
+  ): Promise<UserPreferencesResponseDto> {
+    return this.service.updateMyPreferences(auth, dto);
+  }
+
   @Get('me/license')
   @Authenticated({ permission: Permission.UserLicenseRead })
   @Endpoint({

server/src/controllers/workflow.controller.spec.ts

@@ -95,15 +95,15 @@ describe(WorkflowController.name, () => {
     });
   });
 
-  describe('PUT /workflows/:id', () => {
+  describe('PATCH /workflows/:id', () => {
     it('should be an authenticated route', async () => {
-      await request(ctx.getHttpServer()).put(`/workflows/${factory.uuid()}`).send({});
+      await request(ctx.getHttpServer()).patch(`/workflows/${factory.uuid()}`).send({});
       expect(ctx.authenticate).toHaveBeenCalled();
     });
 
     it(`should require id to be a uuid`, async () => {
       const { status, body } = await request(ctx.getHttpServer())
-        .put(`/workflows/invalid`)
+        .patch(`/workflows/invalid`)
         .set('Authorization', `Bearer token`)
         .send({});
       expect(status).toBe(400);

server/src/controllers/workflow.controller.ts

@@ -1,5 +1,5 @@
-import { Body, Controller, Delete, Get, HttpCode, HttpStatus, Param, Post, Put, Query } from '@nestjs/common';
-import { ApiTags } from '@nestjs/swagger';
+import { Body, Controller, Delete, Get, HttpCode, HttpStatus, Param, Patch, Post, Put, Query } from '@nestjs/common';
+import { ApiExcludeEndpoint, ApiTags } from '@nestjs/swagger';
 import { Endpoint, HistoryBuilder } from 'src/decorators';
 import { AuthDto } from 'src/dtos/auth.dto';
 import {
@@ -81,7 +81,7 @@ export class WorkflowController {
     summary: 'Update a workflow',
     description:
       'Update the information of a specific workflow by its ID. This endpoint can be used to update the workflow name, description, trigger type, filters and actions order, etc.',
-    history: HistoryBuilder.v3(),
+    history: new HistoryBuilder().added('v3.0.0').deprecated('v3', { replacementId: 'updateWorkflow' }),
   })
   updateWorkflow(
     @Auth() auth: AuthDto,
@@ -91,6 +91,17 @@ export class WorkflowController {
     return this.service.update(auth, id, dto);
   }
 
+  @Patch(':id')
+  @ApiExcludeEndpoint()
+  @Authenticated({ permission: Permission.WorkflowUpdate })
+  updateWorkflowV3(
+    @Auth() auth: AuthDto,
+    @Param() { id }: UUIDParamDto,
+    @Body() dto: WorkflowUpdateDto,
+  ): Promise<WorkflowResponseDto> {
+    return this.service.update(auth, id, dto);
+  }
+
   @Delete(':id')
   @Authenticated({ permission: Permission.WorkflowDelete })
   @HttpCode(HttpStatus.NO_CONTENT)