A create method adds a new resource to an API from client-provided information. It uses HTTP POST, returns the newly created resource, and targets either the parent resource or a top-level collection. section 7.3.5
Creating chat resources
A ChatRoom is created with POST /chatRooms, while a Message is created with POST /chatRooms/{chatRoom}/messages. Each request supplies a resource, and the response returns the created ChatRoom or Message. section 7.3.5
Listing 7.3 An example of the standard create method
abstract class ChatRoomApi {
@post("/chatRooms") #1
CreateChatRoom(req: CreateChatRoomRequest): ChatRoom; #2
@post("/{parent=chatRooms/*}/messages") #1
CreateMessage(req: CreateMessageRequest): Message; #2
}
interface CreateChatRoomRequest {
resource: ChatRoom;
}
interface CreateMessageRequest {
parent: string;
resource: Message;
}
Inspect the request interfaces and route annotations for top-level and parent-scoped create operations. section 7.3.5
Apply these design rules:
- Prefer server-generated identifiers for new resources; permit consumer-chosen IDs when synchronization or another concrete requirement justifies them. section 7.3.5
- When clients provide an identifier during creation, place it in the resource's id field. section 7.3.5
