What exactly is an HTTP Entity?

Would someone please describe to me what exactly an HTTP entity is?

I am reading the HTTPClient documentation, but I do not really understand what that means?

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.

As said in a comment by @hawkeye-parker, it looks like Entity has been deprecated. Make a search in this 2014 rfc, and you will see about XML entities and message body, but nothing about Http entity.

Nevertheless, HttpClient, but also JaxRS client, have a setEntity() and getEntity() method.

Considering the accepted answer, both libraries are wrong ! HttpClient.setEntity() won't remove previously set headers.

HttpEntity is what you are going to pass in Request(with header) and what you are getting in Response. For Get Request we are passing simple String

 HttpHeaders headers = new HttpHeaders();
 headers.setAccept(Arrays.asList(MediaType.APPLICATION_JSON));
 HttpEntity<String> entity = new HttpEntity<String>(headers);

For Post We are going to pass complete Entity Class

public String createProducts(@RequestBody Product product) {
    HttpHeaders headers = new HttpHeaders();
    headers.setAccept(Arrays.asList(MediaType.APPLICATION_JSON));
    HttpEntity<Product> entity = new HttpEntity<Product>(product,headers);
    
    return restTemplate.exchange(
             "http://localhost:8080/products", HttpMethod.POST, entity, String.class
           ).getBody();
}

Among the good answers that we have here, I believe that is worth to mention something that comes directly from the RFC 2616 (Hypertext Transfer Protocol - HTTP/1.1):

> Entity > > Request and Response messages MAY transfer an entity if not otherwise > restricted by the request method or response status code. An entity > consists of entity-header fields and an entity-body, although some > responses will only include the entity-headers.

In a a nutshell: an Entity may be transferred, and it can be the header + body, or just the header.

Since that there's the link above, I detain myself on making additional comments.

Entity is something like a message, it consists of header, where are metadata such as location,lang,encoding ...

And optionally of a body - it content is formated etc as specified in header

Latest HTTP 1.1 RFC 7230 has used term Payload instead of Entity. Some old documentation still keep referring the old terminology.

Important practical thing to remember about Entity(Payload) is:

If Transfer-Encoding doesn't exist, Message Body = Entity(Payload) Body.

If Transfer-Encoding exists, Entity(Payload) Body has to be obtained by applying proper decoding and extracting.