An HTTP method is a standardized request action that tells a client how it intends to interact with a resource. Standard methods make APIs more predictable: users learn a small action set once and apply it across resources. section 1.3 section 7.0
Apply the standard method whose behavior matches the requested resource operation:
- Get retrieves an existing resource. section 7.2
- List returns a collection of resources. section 7.2
- Create makes a new resource. section 7.2
- Update changes an existing resource, while Replace substitutes the entire resource. section 7.2
- Delete removes an existing resource. section 7.2
Standardization requires consistent behavior, not merely familiar names. Support each method unless the resource provides a documented reason not to; return 405 when the method is unsupported for the resource type, rather than implying that the resource is missing with 404. Distinguish unsupported methods from instance-specific permission failures, which correspond to 403. section 7.3.1 section 7.0
Keep standard methods limited to their stated operation. Repeated identical requests should preserve the method’s defined idempotence properties, and implementations should avoid unrelated side effects. For example, creating and storing an email belongs to Create, while sending it through SMTP is an additional side effect. section 7.3.2 section 7.6
Chat room API
A ChatRoom API can expose CreateChatRoom with POST /chatRooms, GetChatRoom and ListChatRooms with GET, UpdateChatRoom with PATCH, ReplaceChatRoom with PUT, and DeleteChatRoom with DELETE. Child messages use POST to create and GET to list them under a chat room. section 7.3.9
Use custom methods only for genuinely nonstandard interactions after checking the resource layout. A proliferation of custom methods for ordinary actions often signals that the resources or their relationships are poorly modeled. section 9.4
Table 7.1 Standard methods overview (view table figure)
Compare each standard method’s behavior with a concrete ChatRoom example. section 7.2
