A custom create revision method explicitly snapshots a resource at a chosen moment and creates a new revision. It moves revision policy from the API to the user, avoiding unnecessary implicit revisions. section 28.3.2
Design the operation with these rules:
- Give the method one responsibility: capture the resource’s current state as a revision. section 28.3.2
- Generate the revision identifier randomly and set its creation timestamp when persistence completes. section 28.3.2
- Use explicit creation when users, rather than updates, should determine the revision policy. section 28.3.2
Message revision endpoint
Expose POST /{id=chatRooms/*/messages/*}:createRevision. Accept the message identifier, snapshot the current message, and return a Message containing revisionId and revisionCreateTime. section 28.3.2
Listing 28.3 API definition for creating a resource revision
abstract class ChatRoomApi {
@post("/{id=chatRooms/*/messages/*}:createRevision")
CreateMessageRevision(req: CreateMessageRevisionRequest): #1
Message;
}
interface Message {
id: string;
content: string;
// ...
revisionId: string; #2
revisionCreateTime: Date; #2
}
interface CreateMessageRevisionRequest {
id: string; #3
}
Inspect the compact API definition for the custom method, request identifier, and revision metadata. section 28.3.2
