A move method relocates an API resource to a different parent or location, and may also rename its identifier. Use a custom method rather than standard update or create operations because moving can affect child resources, references, metadata, and concurrent users. section 17.0 section 17.6
Design the operation around these rules:
- Accept the resource identifier and destination identifier; when moving across parents, preserve the existing identifier unless user-selected identifiers are supported. section 17.3.1
- Move child resources and update references to the relocated resource when the relationship requires it, considering each resource hierarchy case by case. section 17.6
- Clarify how external data is handled and preserve inherited metadata such as access-control policies. section 17.2
- Make the operation as atomic as the storage system permits, so failures do not leave partially relocated data. section 17.3.6
Moving a message
Expose a custom endpoint such as POST /{id=chatRooms/*/messages/*}:move with a MoveMessageRequest containing id and destinationId. The method returns the moved Message. A top-level resource without user-specified identifiers generally has no meaningful move operation: it has neither a parent to change nor a valid rename target. section 17.2 section 17.3.1
Listing 17.1 Move-and-copy examples using custom methods
abstract class ChatRoomApi {
@post("/{id=chatRooms/*/messages/*}:move") #1
MoveMessage(req: MoveMessageRequest): Message; #2
@post("/{id=chatRooms/*}:copy") #1
CopyChatRoom(req: CopyChatRoomRequest): ChatRoom; #2
}
Browse the concise API shapes for message moving and chat-room copying. section 17.2
Reconsider the resource layout before adding a move method. Frequent moves can indicate poorly chosen identifiers or a parent-child relationship that should be referential instead. Cutting implementation corners risks lost or corrupted data. section 17.4
