What exactly is an HTTP Entity?

Question

An HTTP entity is the majority of an HTTP request or response, consisting of some of the headers and the body, if present. It seems to be the entire request or response without the request or status line (although only certain header fields are considered part of the entity).

To illustrate; here's a request:

POST /foo HTTP/1.1          # Not part of the entity.
Content-Type: text/plain    # ┬ The entity is from this line down...
Content-Length: 1234        # │
                            # │
Hello, World! ...           # ┘

And a response:

HTTP/1.1 200 OK             # Not part of the entity.
Content-Length: 438         # ┬ The entity is from this line down...
Content-Type: text/plain    # │
                            # │
Response body ...           # ┘

Here are 3 simple cases:

Case 1. You're uploading 3 files in a single request. Those 3 files are 3 entities. Each of them has its own Content-Type to indicate what kind of file it is.

Case 2. You're viewing a web page. Browser has downloaded an html file as entity in the background. Since the page could be updated continuously, you may get a totally different entity later.

Case 3. You've got a 304 Not Modified. No entity has been transferred.

In a word, Entity is an optional payload inside an http message(either request or response), so it is a "part-whole" relation between Entity and Message.

Some header fields apply to Message like Transfer-Encoding describe how to transfer message between intermediaries, and thus MAY be added or removed by any application along the request/response chain(hop-by-hop headers). In comparison, those header fields apply to Entity are some properties, which describe entity's size, type, compression algorithm, etc...

Further reading, quoting from RFC 2616 section 1.4, 4.5 and 4.3:

• A request/response chain

     request chain -------------------------------------->
   UA -----v----- A -----v----- B -----v----- C -----v----- O
      <------------------------------------- response chain

The figure above shows three intermediaries (A, B, and C) between the user agent and origin server. A request or response message that travels the whole chain will pass through four separate connections.

• Header fields either for Message or Entity

There are a few header fields which have general applicability for both request and response messages, but which do not apply to the entity being transferred. These header fields apply only to the message being transmitted.

• Header fields for Message could be changed along the chain

Transfer-Encoding MUST be used to indicate any transfer-codings applied by an application to ensure safe and proper transfer of the message. Transfer-Encoding is a property of the message, not of the entity, and thus MAY be added or removed by any application along the request/response chain.

• Relation between message body and entity body

message-body = Transfer-Encoding( Content-Encoding(entity-body) )

where Transfer-Encoding may be "chunked" which means how to transfer the message, and Content-Encoding may be "gzip" that stands for how to compress the entity.

It is an abstraction representing a request or response payload. The JavaDoc is clear on its purpose and various entity types.

I guess the HTTPClient Entity is named according to HTTP Entity.

HTTP is a Protocol which is observed when accessing information from a remote machine through a network. Usually the network is internet and the remote machine is a server.

When you ask for information from person A to person B, you give him a message. (Request). Person B replies to you (Response). Request and Response are HTTP Message Types.

Person A can ask Person B to do something, instead of asking for information. Say, Person A wants Person B to store a file in a secure location. So, Person A passes that file(HTTP Entity) to Person B and ask him to do something(HTTP Message). In this case, Person is passing an "Entity". In the context of HTTP Entity, it is a payload attached with the message.

Hope the analogy helped.