This question already has answers here:
What exactly is an HTTP Entity?
(10 answers)
Closed 9 years ago.
Now I know what's an http entity. But what's entity used for?
I mean, when an application manipulates an http request or response, it just need to know how to parse message head and message body. Then what's the role of an entity? They have almost similar structures.
I dont really understand what you are trying to ask?
If you mean can we skip using HttpEntity in response and request at all? The answer is no!
its a convention you have to follow it, that how internet works!
Quoting entities from apache documentation:
Since an entity can represent both binary and character content, it
has support for character encodings (to support the latter, ie.
character content).
The entity is created when the request was successful, and used to
read the response.
To read the content from the entity, you can either retrieve the input
stream via the HttpEntity.getContent() method, which returns an
InputStream, or you can supply an output stream to the
HttpEntity.writeTo(OutputStream) method, which will return once all
content has been written to the given stream.
When the entity was received as a result of a response, the methods
getContentType() and getContentLength() methods are for reading the
common headers Content-Type and Content-Length respectively (if they
are available). Since the Content-Type header can contain a character
encoding for text mime-types like text/plain or text/html, the
getContentEncoding() method is used to read this information. If the
headers aren't available, a length of -1 will be returned, and NULL
for the content-type. If the Content-Type header is available, a
[Header] object will be returned.
When creating an entity for a request, this meta data has to be
supplied by the creator of the entity.
Other headers from the response are read using the getHeaders()
methods from the response object.
Source: http://wiki.apache.org/HttpComponents/HttpEntity
And I'm again sorry if I didn't get your question right, but hope this helps anyways.
Related
Chapter 9.5 POST of the HTTP/1.1 spec includes the sentence:
If a resource has been created on the origin server, the response
SHOULD be 201 (Created) and contain an entity which describes the
status of the request and refers to the new resource, and a Location
header
It is referenced frequently. The itention is clear, but I have issues with the meaning of some of the chosen words.
What does "contain an entity which describes the status of the request and refers to the new resource" exactly mean?
How shall the entity (entity-header fields and entity-body) describe the status of the request? Isn't the status of the request 201 (Created)? Whow shall this status be described? Does "describe the status of the request" mean the result, in other words the current entity status?
Thinking of a Web API with JSON representation does it mean that the entity should be included in a JSON representation after a successful POST that created an entity? Thinking of a created image, should the image data be returned in the response body?
What is meant with refers to the new resource? The uri is already in the location header. Shall it be repeated in the body or does it mean just to add an id?
Is there a good source with examples of different entities and its responses to a creation POST?
I think it varies based on the resource you're creating, suppose your posting to a /profile/ resource maybe a payload containing multiple profile fields to update - your return would indicate it was successful and include a reference to the fields you posted (it can even return the entire profile attributes with fields you've updated including all fields);
Another example in the image sense, suppose you are posting a Base64 encoded image to a service that stores the image, the response should show the status (ie: accepted, rejected, file too larage, MIME type accurate or not, etc.) - and within the returned payload if successful you'd want the response to not be vague but return the path and/or filename of the image uploaded;
The header returns the response code - the body returns information related to the invoked action's entity response (it can be a set of fields, a URL, a useful response that when parsed back it can be actionable or informative);
These are principles of good coding, but also keep note of security and not to expose anything in a return that could potentially be damaging for example; when creating a service you want to be clear and provide concise and useful returns so when the client consumes the API it knows what to do, what to expect, etc.
In a 406 Not Acceptable response:
The server SHOULD generate a payload containing a list of available
representation characteristics and corresponding resource identifiers
from which the user or user agent can choose the one most appropriate.
A user agent MAY automatically select the most appropriate choice from
that list. However, this specification does not define any standard
for such automatic selection, as described in RFC7231 Section 6.4.1.
Is there a preferred format for that "list of available representation characteristics and corresponding resource identifiers"?
I can send a response like:
{ Acceptable: ["application/json", "application/pdf"] }
But then I am assuming a default Content-Type for the 406 payload (JSON in this case).
Or should I send a very simple, almost format-less, payload like:
application/json,application/pdf
Is there a preferred format for that "list of available representation characteristics and corresponding resource identifiers"?
There's no standard for such payload.
You could choose any format that can be easily parsed by the user agent. In practice, both JSON or text should be fine:
{ "acceptable" : [ "application/json", "application/pdf" ] }
application/json,application/pdf
See the following quote from the section 6.4.1 of the RFC 7231, which is referenced in the 406 status code definition:
[...] A specific format for automatic selection is not defined by
this specification because HTTP tries to remain orthogonal to the
definition of its payloads. In practice, the representation is
provided in some easily parsed format believed to be acceptable to
the user agent, as determined by shared design or content
negotiation, or in some commonly accepted hypertext format. [...]
MDN Web Docs from Mozilla suggests the following:
[...] In reality, this error is very rarely used: instead of responding using this error code, which would be cryptic for the end user and difficult to fix, servers ignore the relevant header and serve an actual page to the user. It is assumed that even if the user won't be completely happy, they will prefer this to an error code. [...]
I'm implementing an API method that allows for exporting some data to a file. The format of the file is selected by the caller of the method.
The API method currently has an URI-form like so: /customers/{customerId}/shoppingchart/export/{fileTypeId} but what is the "correct" Http-way, if any, to implement the file type selection? Should the choice be specified by the Http Accept header or in the URI or some other way? And, what is the correct status to return if the asked format isn't supported?
I agree with the HTTP Accept header to specify the file type.
RFC 2616 states:
The Accept request-header field can be used to specify certain media types which are acceptable for the response.
However this does not indicate whether you can create your own custom types (should you wish that).
The HTTProtocol describes an Accept header as this:
This field contains a semicolon-separated list of representation schemes (Content-Type metainformation values) which will be accepted in the response to this request.
The above link then points to the definition of a Content-Type exactly. What's important here is
The x- convention for experimental types is of course still available as well.
This tells us that we can define our own custom types in an Accept header given that we prepend them with x- (e.g. x-ext for .ext files) as is common in the HTTProtocol.
What is the correct status to return if the asked format isn't supported?
I would argue HTTP 415 - Unsupported Media Type as defined in section 10.4.16 is appropriate here.
The server is refusing to service the request because the entity of the request is in a format not supported by the requested resource for the requested method.
I'm writting a RESTful api, and at I'm thinking about the process of a user creating a key. I have the following possibilities:
GET request to /new/<keyname> - although it's very easy I think I won't use this, because I heard GET is for retrieving and/or listing information;
POST request to /<keyname> - This seemed to me easy and simple enough, but does not pass any data in the request body. Can I do it this way ? Is this weird ?
POST request to /keys passing in the request body "keyname=SomeKey" - Is this the correct way ?
I looked at this API from joyent and in all their PUT and POST requests they pass some data in the request body. Is this expected ? Is it really wrong not to require a request body in a PUT and POST request ?
I asked this question on the Http-WG. This was the most precise answer I got http://lists.w3.org/Archives/Public/ietf-http-wg/2010JulSep/0276.html
In summary, POST does not require a body. I would expect the same justification can be applied to PUT.
RFC2616 is the base RFC for HTTP 1.1
In the most general form, an HTTP message is this (note the optional body):
generic-message = start-line
*(message-header CRLF)
CRLF
[ message-body ]
start-line = Request-Line | Status-Line
Reading further gives this:
9.5 POST
The POST method is used to request that the origin server accept the
entity enclosed in the request as a new subordinate of the resource
identified by the Request-URI in the Request-Line. ...
and
9.6 PUT
The PUT method requests that the enclosed entity be stored under the
supplied Request-URI. ...
The fundamental difference between the POST and PUT requests is
reflected in the different meaning of the Request-URI. The URI in a
POST request identifies the resource that will handle the enclosed
entity. That resource might be a data-accepting process, a gateway to
some other protocol, or a separate entity that accepts annotations.
In contrast, the URI in a PUT request identifies the entity enclosed
with the request -- the user agent knows what URI is intended and the
server MUST NOT attempt to apply the request to some other resource.
Both POST and PUT include the phrase entity enclosed in the request.
Based on my reading, I believe that a body is desired (a non-normative description, I know) for both POST and PUT.
In the context of REST, POST is create and PUT is update. I can imagine creating an empty object (perhaps a placeholder for future information), but I don't imagine much use of an empty update.
It is not required. You can send a POST/PUT request without a body and instead use query string parameters. But be careful if your parameters contain characters that are not HTTP valid you will have to encode them.
For example if you need to POST 'hello world' to and end point you would have to make it look like this: http://api.com?param=hello%20world
Probably the best way is your third option: POST to /keys with keyname=SomeKey.
Here's why: You may wish to add another function to your API, for example create_new_user. It would then be difficult to tell the difference between a user trying to POST a key called create_new_user and a user trying to use the create_new_user function.
You are correct in saying that you should not be using GET to do this operation as the GET operation "SHOULD NOT have the significance of taking an action
other than retrieval." (RFC 2616).
To answer your question in one line. Yes it is expected to have Body/Content in body, but it is not required(Mandatory).
According to okHttp3 (an HTTP library for android): the following methods need a body: POST, PUT, PATCH, PROPPATCH (WebDAV) and REPORT (source). It even crashes if you try to do a request with the given methods without a body.
"Accept" is not listed in the forbidden headers in the documentation here:
http://livedocs.adobe.com/flash/9.0/ActionScriptLangRefV3/flash/net/URLRequestHeader.html
but cant seem to set it in a GET request. Help!
You are allowed to specify the "accept" header, but only on a POST request with one or more variables.
The documentation comments mention this:
For browser-based Flash/AS3 applications, the only way to successfully set
or modify request headers on a URLRequest object is to set its method to
POST as well as send at least one variable of data along with the request
(i.e. with URLVariables). Otherwise the headers will silently remain
unchanged.