Idempotency means that repeating the same request with identical parameters produces the same effect as executing it once. It supports predictable API behavior, but not every standard method must be idempotent. section 7.3.2 section 7.6
Separate idempotency from side effects. Creating and storing an email belongs to the create operation; sending it through SMTP is an additional side effect that standard methods should avoid. Even a hidden request counter can undermine idempotency when it affects performance or failure behavior. section 7.3.2
Apply these rules when designing resource-oriented methods:
- Keep repeated requests behaviorally predictable and avoid work that changes unrelated API state. section 7.0 section 7.6
- Decide whether a method is declarative or imperative before defining repeated-request results. section 7.3.7
- Document errors for requests whose desired state already holds when the operation is intended to report an action rather than a result. section 25.3.3
- Use validation-only behavior when full request execution would introduce non-idempotent effects or external dependencies. section 27.3
Deleting a ChatRoom twice
A declarative DELETE request means “ensure this ChatRoom no longer exists.” Repeating it succeeds because the same result remains true. An imperative interpretation means “remove this resource now”; the first request succeeds, while the second fails because there is nothing left to remove. Choose and document the behavior deliberately. Soft deletion adds a recovery path: a custom undelete operation restores a resource, but calling it for a resource that is not soft-deleted returns an error such as 412 Precondition Failed. section 7.3.7 section 25.3.3
Listing 7.5 The standard delete method
abstract class ChatRoomApi {
@delete("/{id=chatRooms/*}") #1
DeleteChatRoom(req: DeleteChatRoomRequest): void; #2
}
interface DeleteChatRoomRequest {
id: string;
}
Shows a standard DELETE method targeting a ChatRoom resource by identifier and returning an empty response. section 7.3.7
