Currently we're developing a RESTful service that has a requirement to return (echo) the newly created/updated resource entity in certain scenarios and alternatively echo nothing back in others; therefore saving network load.
Two solutions have been presented.
Query Variable
POST http://service/resource?echo=false
Accept Header
if ( request.has_header( "Accept" ) )
echo back newly created resource
else
ignore
Is the second scenario improper use of HTTP Headers?
As you've already surmised, the second usage is an improper use of that header. The principle of a "correct" RESTful interface is one that adheres to HTTP standards. Adhering to the standard means using the grammar of HTTP the way it's prescribed. The second proposal would qualify as as not using it as prescribed. Don't take it from me (what do I know), take it from the HTTP spec itself
The Accept request-header field can be used to specify certain media types which are acceptable for the response. Accept headers can be used to indicate that the request is specifically limited to a small set of desired types
That's it. It's meant to be used for Content Negotiation (AKA Conneg); repurposing it, while possible, is frowned upon
Related
I got a query while developing rest service.
As per the REST design, GET is to read , PUT or POST are to create or update based on scenario , DELETE is to delete the resources.
But technically, Can't we perform a create or delete operation in GET call.
i.e. It is up to client way of calling by using specified URL pattern and required response type to hit the exact method in the service class of REST application. But why can't we perform a delete or create of some data in the GET service.
so my question is the DELETE or CREATE technically not possible in GET service or is it a rule to adhere to REST principles.
so my question is the DELETE or CREATE technically not possible in GET service or is it a rule to adhere to REST principles.
The latter. It is only a convention to use the DELETE HTTP method for delete operations. However using the GET HTTP method for delete operations is a bad idea. Below is a quote from "RESTful Java with JAX-RS 2.0, 2nd Edition" that explains why:
It is crucial that we do not assign
functionality to an HTTP method that supersedes the specification-defined boundaries
of that method. For example, an HTTP GET on a particular resource should be readonly.
It should not change the state of the resource it is invoking on. Intermediate services
like a proxy-cache, a CDN (Akamai), or your browser rely on you to follow the semantics
of HTTP strictly so that they can perform built-in tasks like caching effectively. If you
do not follow the definition of each HTTP method strictly, clients and administration
tools cannot make assumptions about your services, and your system becomes more
complex
so my question is the DELETE or CREATE technically not possible in GET
service or is it a rule to adhere to REST principles?
REST uses standards aka. uniform interface constraint. One of these standards is the HTTP standards which defines the HTTP methods. According to the HTTP standard the GET is a safe method:
In particular, the convention has been established that the GET and
HEAD methods SHOULD NOT have the significance of taking an action
other than retrieval. These methods ought to be considered "safe".
This allows user agents to represent other methods, such as POST, PUT
and DELETE, in a special way, so that the user is made aware of the
fact that a possibly unsafe action is being requested.
According to the RFC 2119:
SHOULD NOT - This phrase, or the phrase "NOT RECOMMENDED" mean that there may exist valid reasons in particular circumstances when the particular behavior is acceptable or even useful, but the full implications should be understood and the case carefully weighed before implementing any behavior described with this label.
For example write can be a side effect by GET, if you want to increase the visitor count by each request.
How the server software (API) is constructed and what 'rules' are applied is somewhat 'arbitrary'. Developers and their product managers could enforce 'rules' such as 'thou shalt not code or support DELETE operations through the GET operation', but in practice, that is not necessarily the main reason POST is chosen over GET. As others have mentioned, there may be assumptions based on the HTTP protocol that other vendors may rely on, but that is a rather complex and not necessarily relevant reasoning. For instance, your application may be built to connect directly to a server application, and another vendor's rules may not apply.
In a simpler example, on the world wide web and due to compliance and other factors, query string has a limited byte length. Because of this, operations that require a lot of data, such as a few very long encrypted data strings that might be needed for a DELETE operation in a database, GET may not be able to pass enough data, so POST may be the only viable option.
Custom built applications using a CuRL library might extend to include other RESTful operations with their intended functionality, but that would be for the benefit of the server API. Coding more operations on the client-side doesn't necessarily make things 'easier', 'faster', or necessarily 'more secure' from the client perspective, but doing so could help manage resources (a bit) on the server side and help maintain compatibility with third party software and appliances.
I am creating a REST-API and am encountering a problem where the client needs to get a calculation based on a lot of different parameters.
This GET operation might not be a part of any Save or Update operations (before the GET or after), and can happen in a stateless manner.
Due to this the GET URL can be very long (and even exceed the maximum allowed by the browser).
I have looked in other posts here in SO and elsewhere and it is discouraged to use a body in GET requests. But whats most important about all these posts is that none of them give an alternative to this problem they just state that something is flawed in the design ETC...ETC...
Well nothing is wrong with the design here. its a stateless calculation built on a lot of parameters.
I would like some alternatives. Thank you.
nothing is wrong with the design here
There is. From Wiki:
An important concept in REST is the existence of resources (sources of specific information), each of which is referenced with a global identifier (e.g., a URI in HTTP).
Your calculation parameters have nothing to do with the underlying resource identified by the URL you make the request to. You're not requesting an existing resource (as that's what GET is for, depending on how you're willing to interpret REST), but some calculations will be done based on some input. This is a Remote Procedure Call, not a REST call.
You can change your approach by modeling a Calculation, so you send a POST /Calculations/ request with all your parameters.
There's no requirement for a POST call to change server state (i.e. store the results):
httpbis-draft, POST (which is somewhat better worded and updated than RFC 2616):
The POST method requests that the target resource process the
representation enclosed in the request according to the resource's
own specific semantics.
POST is used for (among others): providing a block of data, such as the fields entered into an HTML
form, to a data-handling process;
So you can just return the calculation results along with a 200, or you can store them and return a 200, 201 or 204, containing or pointing to the calculation results, so you can retrieve them later, using GET /Calculations/$id.
As far as I can tell, the only solution you have left is to break the rules of REST and use a POST request. POST can have an arbitrary number of arguments, but it's meant for a "modification" operation in REST.
Like everything in software, the rules are there to help you avoid mistakes. But if the rules prevent you from solving your problems, you need to modify them a little bit (or modify them for a well defined part of your code).
Just make sure that everyone understands how you changed the rules, where the new rules apply (and where they don't). Otherwise, the next guy will "fix" your "broken" code with his simple test cases.
So you want a safe HTTP method that accepts a payload. Have a look at http://greenbytes.de/tech/webdav/draft-ietf-httpbis-method-registrations-14.html - both SEARCH and REPORT are theoretical candidates, if you can live with the WebDAV baggage they come with.
An alternative would be to start work on either generalizing these, or defining something new (but don't forget that definitions of new HTTP methods need IETF review, see http://greenbytes.de/tech/webdav/draft-ietf-httpbis-p2-semantics-25.html#considerations.for.new.methods.
Is there any accepted naming convention for custom http headers in an in-house web application?
in-house in the strict sense means that requests with this header will never be transmitted over the public internet. in-house in a liberal sense means that while requests may be transferred over the public internet the server endpoint will always be a machine under control of a specific vendor.
i am aware of this SO article and the RFC 6648.
However, the reasoning forwarded in the latter reference does not quite convince me as it says:
2. SHOULD employ meaningful parameter names that they have reason to
believe are currently unused.
3. SHOULD NOT prefix their parameter names with "X-" or similar
constructs.
Well, X-<meaningful_name> conveys the semantics suggested by <meaningful_name> + the information that this header has neither been assigned by nor registered with an official standard maintaining authority, so the items 2., 3. appear a bit contradictory.
Of course, I could use other monikers like Vnd- or a company/product name prefix or even a customary term like Foo-. the arguments against the X- prefix would still apply, however.
On the other hand, just using a 'meaningful name' invites future collisions with the same term being endorsed by an official standard or some other company whose products will become part of the processing pipeline.
ps:
apologies if this question is considered overly unspecific. I'll be happy to move it to some other more suitable venue.
Yes, there is a accepted naming convention.
VND.{domain}.{key}
Example: VND.wreckingballmedia.com.runtime = 102ms
You can read the official recommendation here: https://www.rfc-editor.org/rfc/rfc6648
It basically says that everyone thought "X-MyNonStandardHeader = Value" was a good idea but there are still naming collisions. It says you might get away with UUIDs or something, but, they recomend the VND.domain.key format.
I want to provide different answers to the same question for different users, based on the access rights. I read this question:
Excluding private data in RESTful response
But I don't agree with the accepted answer, which states that you should provide both /people.xml and /unauthenticated/people.xml, since my understanding of REST is that a particular resource should live in a particular location, not several depending on how much of its information you're interested in.
The system I'm designing is even more complicated than that one. Let's say that a user has created a number of circles of friends, and assigned different access rights to them. For example, my "acquaintances" circle might have access to my birthday, and my "professional" circle might have access to my employment history, but not the other way around. In order to apply the answer from the question I mentioned, I need to have a way of getting all of the user's circles (which I might want to keep secret for security reasons), and then go through /circles/a/users/42, /circles/b/users/42, /circles/c/users/42 and so on, and then merge the results to display the maximum amount of information available. Obviously there's not necessarily a single circle that gets all the information that any of the other circles get. I believe this is tricky enough (note that I probably need to do this with several kinds of objects and that future versions might require a different procedure), but what if I want to impose security restrictions on a particular user despite the fact that he's also in some of my circles? Can that problem even be solved? Even if I refuse to respond to any of the above-mentioned queries and come up with a new one that could give me an answer, it'd still reveal the fact that this specific user is treated differently due to individual access restrictions.
What am I missing here? Is it even possible for me to develop a RESTful web service?
If the conclusion is that the behavior is not RESTful, would this still constitute as a situation where it'd be morally okay to break the REST contract? If so, what are the negative implications? Do I risk proxy caching issues for example?
According to Fielding's dissertation (it really is a great writing):
A resource is a conceptual mapping to a set of entities, not the entity that corresponds to the mapping at any particular point in time.
In other words, if you have a resource that is defined as "the requesting user's assigned projects" and representations thereof accessible by a URI of /projects, you do not violate any constraints of REST by returning one list of projects (i.e., representation) for user A and another (representation) for user B when they GET that same URI. In this way, the interface is uniform/consistent.
In addition to this, REST only prescribes that an explicit caching instruction be included with the response, whether that is 'cache for this long' or 'do not cache at all':
Cache constraints require that the data within a response to a request be implicitly or explicitly labeled as cacheable or non-cacheable.
How you choose to manage that is up to you.
Keeping that in mind,
You should feel comfortable returning a representation of a resource that varies depending on the user requesting a representation of a particular resource, as long as you are not violating the constraints of a uniform interface -- don't use a single resource identifier to return representations of different resources.
If it helps, consider that the server responds with varying representations of a resource as well -- XML or JSON, French or English, etc. The credentials sent with the request are just another factor the server is able to use in determining which representation to to send in response. That's what the header section is there for.
I agree that the other solution doesn't seem right. It makes the URL structure complicated and more difficult to find the resource. However, if you did REST properly, it shouldn't matter what the URL for the resource is as the server controls it (and is free to relocate it as it sees fit). If your client is really "REST", it would discover the resources it needed through prior negotiation with the server. So the path truly would not matter on the client. I don't like it because its confusing to use - not because of some violation of REST principles.
But that probably doesn't answer your question -
What you didn't mention is your security setup - presumably you are a passing a session token with the request as part of the request header. So your back-end processing should have the ability to tie it to particular set of security constraints. From there, you form the list with whatever business logic you need and return a limited resource based on the user's security tied to the session.
For the algorithm itself, one usually implements a least or most restrictive type algorithm that merges the allowable data into a response (very similar to java realms or Microsoft's user security model).
If the data is structured differently for the restricted/non-restricted case, you could create two different representations of the data and return which ever one the user was authorized to see. The client should be asking for the accepted mime response types anyway, and it would just provide different answers based on the session security in the request header. Alternatively, you could provide optional elements with the representations and fill out the appropriate one base on authorization (although this is a little hack-ee in my opinion).
What is the minimum set of HTTP verbs that a server should allow for a web service to be classed as RESTful?
What if my hoster doesn't permit PUT and DELETE?
Is this actually important, can I live happily ever after with just GET and POST ?
Update: Thanks for the answers folks, Roger's answer was probably best because of the link to the Bill Venners and Elliotte Rusty Harold interview. I now get it.
Yes, you can live without PUT and DELETE.
This article tells you why:
http://www.artima.com/lejava/articles/why_put_and_delete.html
While to true RESTafrians this may be heresy, in the real world you do what you can, with what you have. Be as rational as you can and as consistent with your own convention as you can, but you can definitely build a good RESTful system without P and D.
rp
You can also use X-Http-Verb-Override:DELETE inst. of HTTP DELETE. This is also usefull for Silverlight clients who cant change the HTTP verbs and only support GET and POST...
If you just use GET and POST, it's still RESTful. Your web service may only do things which only required GET or POST, so that's fine.
REST allows for breaking protocol convention if the implementations of the protocol are broken (so that the only non-standard things you do are to get around the broken parts of the implementation). So it is allowable within REST to use some other method to represent generally unsupported verbs like DELETE or PUT.
edit: Here is a quote from Fielding, who is the one that created and defined REST:
A REST API should not contain any changes to the communication protocols aside from filling-out or fixing the details of underspecified bits of standard protocols, such as HTTP’s PATCH method or Link header field. Workarounds for broken implementations (such as those browsers stupid enough to believe that HTML defines HTTP’s method set) should be defined separately, or at least in appendices, with an expectation that the workaround will eventually be obsolete. [Failure here implies that the resource interfaces are object-specific, not generic.]
Today's web browsers only handle GETS + POSTS. In Rails, for example, PUTS + DELETES are "faked" through hidden form fields.
Unless your framework has some workaround to "support" PUTS + DELETES, don't worry about them for now.