I'm playing with the Twitter API and noticed something funny- For updates, they require POST methods but expect the arguments in the query string. (See for example, the status/update call in their developer console here.)
Obviously this is technically possible, but why would anyone do it like that? Don't POST arguments belong in the body?
Either option is just as valid. My favourite example for using parameters in the URL for a POST is an application that sets waypoints on a map. e.g.
POST /map/route/45/waypoints?lat=35&long=74
In this case, the parameters make more sense in the URI as identifiers of a location, than just parameters being passed in the body to generic resource.
In REST architecture, GET and POST are just the verbs, which tells either to retrieve or create/update the resource. URI defines the identification of resource.
Example:
POST /student?name=Tom&age=12 >> It will create a new student with name Tom and age 12.
POST /student/10?name=Tom&age=12 >> It will update student with id 20 with name Tom and age 12.
There is no rule that the data should be binded to body payload or URI. This is different from WEB 1.0 concepts where HTML form data is sent in POST.
If the arguments for WEB API are in the body or query depends on the Content-Type header you send in the POST.
If it forinstance is Content-Type: application/json; charset=UTF-8 then the arguments are expected in the body as json. If it is Content-Type: application/x-www-form-urlencoded; charset=UTF-8 then the arguments are expected in the query string
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.
I want to issue a 406 Not Acceptable error in my application and I want to alert the client about the available alternative formats.
From the HTTP protocol spec:
Unless it was a HEAD request, the response SHOULD include an entity
containing a list of available entity characteristics and location(s)
from which the user or user agent can choose the one most appropriate.
The entity format is specified by the media type given in the
Content-Type header field. Depending upon the format and the
capabilities of the user agent, selection of the most appropriate
choice MAY be performed automatically. However, this specification
does not define any standard for such automatic selection.
Do I add that entity in the response body?
What's the format of that list?
The main thing in the spec is:
The entity format is specified by the media type given in the Content-Type header field
This page is quite useful:
http://chimera.labs.oreilly.com/books/1234000001708/apc.html#_proactive_negotiation
As-is the article it references:
http://bit.ly/agent-conneg
The examples there describe negotiation, in situations where you would return a 300 Multiple Choices response, a situation similar to how you might provide alternatives in a 406 Not Acceptable response. It follows the same ideas where you provide an entity in the format of the returning content type - if you are returning text, write some text; if you are returning HTML, write some HTML.
HTTP/1.1 300 Multiple Choices
Host: www.example.org
Content-Type: application/xhtml
Content-Length:XXX
<p>
Select one:
</p>
French
US English
German
A standard format would indeed be useful for automatic renegotiation, but the spec stays away from defining that. I would agree with the writer that the best way to inform of alternatives to a 406 is to use the same "Link" headers in the example from the oreilly.com page, as they describe:
An alternative approach is to use Link headers. This has the advantage of being a standard header that any client can understand. Here is an example:
HTTP/1.1 300 Multiple Choices
Host: www.example.org
Content-Length: 0
Link: <http://www.example.org/results/png>; type="image/png",
<http://www.example.org/results/jpeg>;type="image/jpeg",
<http://www.example.org/results/gif>;type="image/gif"
However, don't expect guaranteed results on every client with something that is not standardized.
I know that clients and servers most commonly communicate through HTTP forms. I know enough about the GET methods, but the little I do know about POST methods is that they're used to submit data to the server. However, when the server receives a POST method and processes the data, it sends a status code like 200 etc., but how does the server send more data? I know there's a body but what does it look like? Does it have parameters and values just like a POST method?
The format of the body is specified in the Content-Type header.
A commonly used Content-Type for form data submission is application/x-www-form-urlencoded. The body for such a request should look something like this:
key1=value1&key2=value+with+spaces
Where key1 and key2 are input names and value1 and value+with+spaces are the corresponding values. Note that key names and values are url encoded
Another common type is application/json, which means the request body should be interpreted as JSON data, for example:
{
"key": "value",
"another_key": "value"
}
So it's just data, and the Content-Type header tells the server how to interpret it.
Edit: A good way to see what's going on is create a form with method="post", and analyze the request with your browser developer tools when the form is submitted.
Trying to update a data field on a lead record in Marketo. Using C#. I send:
{"action":"updateOnly","input":[{"email":"dfranks#gmail.com","leadQuality":"Hot"}]}
And get back:
{"requestId":"d98e#14b2d7dd1f3","success":false,"errors":[{"code":"612","message":"Invalid Content Type"}]}
Why the Invalid Content type message? The field leadQuality is legit. The email address exists. I've tried a number of different fields and always the same message. Access token is good too.
Content-Type is a HTTP header. Usually, you set it to application/json for REST calls.
You should do this in the code where you generate the HTTP request or REST call.
I found text/json as Content-Type and Accept header value in one of the marketo examples. You might try one of the two choices.
Here are a couple of things to check:
As #StephenKing mentioned, I would check that your Content-Type HTTP
Header is set to "application/json".
I would also confirm that the custom field you created for "leadQuality"
has a String data type.
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.