3.1. Generic Semantics

3.1. Generic Semantics

Much of the value of HTTP is in its generic semantics -- that is, the protocol elements defined by HTTP are potentially applicable to every resource and are not specific to a particular context. Application-specific semantics are best expressed in message content and header fields, not status codes or methods (although status codes and methods do have generic semantics that relate to application state).

This split between generic and application-specific semantics allows an HTTP message to be handled by common software (e.g., HTTP servers, intermediaries, client implementations, and caches) without requiring those implementations to understand the application in use. It also allows people to leverage their knowledge of HTTP semantics without needing specialised knowledge of a particular application.

Therefore, applications that use HTTP MUST NOT redefine, refine, or overlay the semantics of generic protocol elements such as methods, status codes, or existing header fields. Instead, they should focus their specifications on protocol elements that are specific to their application -- namely, their HTTP resources.

See [BCP190] for more information.

When writing a specification, it's often tempting to specify exactly how HTTP is to be implemented, supported, and used. However, this can easily lead to an unintended profile of HTTP's behaviour. For example, it's common to see specifications with language like this:

A POST request MUST result in a 201 Created response.

This forms an expectation in the client that the response will always be 201 Created when, in fact, that response is not at all certain. It's only expected when the server believes that a new resource has been created, but various reasons (such as security policy) might prevent the server from creating a new resource or confirming that the resource has been created.

More appropriate language would be:

A successful POST request SHOULD result in a 201 Created response when a resource has been created.

A specification can use specific instances of protocol elements to signalise application-specific semantics. In a sense, this is how the generic semantics are specialised for the application. For example, an application might define a POST request with a specific Content-Type to mean "create a new resource with the enclosed representation". Because the semantics are application-specific, they need to be defined in the application's specification.

See Section 4.7 for specifics on application-defined header fields.