Despite the ubiquity of the web, many have had difficulties applying the architectural principles of the web to their systems. Representational State Transfer (REST), the architecture behind the web is quickly becoming a real alternative to be considered by architects developing distributed systems. In a recently released InfoQ article, Stefan Tilkov delves into the ways of designing systems using REST and examines the similarities and differences between classic interface-based approaches.
Read A Brief Introduction to REST.First outlining the key principles of REST, Tilkov flattens much of the learning curve of this much-debated architecture:
- Give every "thing" an ID
- Link things together
- Use standard methods
- Resources with multiple representations
- Communicate statelessly
Some of the benefits outlined include:
[A] consistent naming scheme for things [so] that you don't have to come up with your own scheme — you can rely on one that has already been defined, works pretty well on global scale and is understood by practically anybody.
As well as:
[A] uniform interface [that] enables every component that understands the HTTP application protocol to interact with your application. Examples of components that benefit from this are generic clients such as curl and wget, proxies, caches, HTTP servers, gateways, even Google/Yahoo!/MSN, and many more.
For those interested in more of the theory behind REST, Tilkov also gives the background as well as links to the definitive works on the subject.
Community comments
Love the analogy
by Peter Lacey,
Re: Love the analogy
by Mike Glendinning,
Re: Love the analogy
by Felipe Nascimento,
Re: Love the analogy
by Stefan Tilkov,
Re: Love the analogy
by Mike Schinkel,
REST on .NET?
by Ole Friis,
Re: REST on .NET?
by Stefan Tilkov,
Re: REST on .NET?
by Vlad Bezden,
RESTful with many parameters?
by Tom Dyer,
Re: RESTful with many parameters?
by Rafael de F. Ferreira,
Re: RESTful with many parameters?
by Tom Dyer,
Re: RESTful with many parameters?
by lipman li,
Re: RESTful with many parameters?
by Kirstan Vandersluis,
Re: RESTful with many parameters?
by Tom Dyer,
Re: RESTful with many parameters?
by Mike Schinkel,
Re: RESTful with many parameters?
by Stephan Schlöpke,
Re: RESTful with many parameters?
by Kirstan Vandersluis,
Re: RESTful with many parameters?
by Stephan Schlöpke,
Re: RESTful with many parameters?
by Kirstan Vandersluis,
Re: RESTful with many parameters?
by Stephan Schlöpke,
Re: RESTful with many parameters?
by Ally Kendall,
Re: RESTful with many parameters?
by Torben Wölm,
very nice
by Nikita Ivanov,
Representations
by Jim Standley,
Re: Representations
by Tom Dyer,
c# Interface analogy
by Maximilian Schulz,
Resource graph traversal is not the same as state transition
by Ganesh Prasad,
Re: Resource graph traversal is not the same as state transition
by Stephan Schlöpke,
Re: Resource graph traversal is not the same as state transition
by Stefan Tilkov,
Re: Resource graph traversal is not the same as state transition
by Ganesh Prasad,
Re: Resource graph traversal is not the same as state transition
by Mike Schinkel,
What when REST semantics are not enough?
by Gael Fraiteur,
Re: What when REST semantics are not enough?
by Ally Kendall,
Re: What when REST semantics are not enough?
by Mike Schinkel,
Re: What when REST semantics are not enough?
by Stefan Tilkov,
Excellent
by Sadek Drobi,
Architecture of resources ?
by Vladimir Vacula,
Re: Architecture of resources ?
by Stefan Tilkov,
Re: Architecture of resources ?
by Mike S,
Re: Architecture of resources ?
by Mike Schinkel,
Understanding the Difference!
by William Martinez,
So IOW, this applies only to web projects. What about Windows projects?
by Parimal Jisaheb,
Re: So IOW, this applies only to web projects. What about Windows projects?
by Stefan Tilkov,
Re: So IOW, this applies only to web projects. What about Windows projects?
by Mike Schinkel,
Re: So IOW, this applies only to web projects. What about Windows projects?
by Florian Schwarz,
Thanks
by Yuen Chi Lian,
Question about use of Cookies
by Matthias K.,
Re: Question about use of Cookies
by Stefan Tilkov,
Re: Question about use of Cookies
by m k,
RESTful transaction service
by Ian Goldsmith,
Re: RESTful transaction service
by Stefan Tilkov,
Re: RESTful transaction service
by Mark Little,
Send large result set
by John John,
Do you suppose that all possible actions can be reduced to 4 verbs?
by Mark Kamoski,
Use of Accept to define required representation
by Martin Haigh,
Re: Use of Accept to define required representation
by Stefan Tilkov,
Rest URI design with URL parameters
by Thomas Tkac,
UML Diagrams
by Ersoy Hasanoglu,
Re: UML Diagrams
by Stefan Tilkov,
Re: UML Diagrams
by Ersoy Hasanoglu,
Re: UML Diagrams
by peng zhang,
well writen, and very easy to understand!
by phoenix bai,
Re: well writen, and very easy to understand!
by Stefan Tilkov,
REST & standard behavior
by Dan Noonen,
Thank you for a clear explanation
by Anuradha Va,
Love the analogy
by Peter Lacey,
Your message is awaiting moderation. Thank you for participating in the discussion.
Brilliant.
REST on .NET?
by Ole Friis,
Your message is awaiting moderation. Thank you for participating in the discussion.
At the project I'm currently working on, it would be really nice to have a REST interface instead of the SOAP interface we're currently going for. The reason we're going for SOAP is that the project is done in .NET 2.0, and the .NET framework has excellent support for SOAP.
However, I have not been able to find good .NET REST frameworks. Microsoft is doing Astoria, but that's a "let's publicise your database through the Web" thing, and besides that it requires WCF and thus .NET 3.
Does anybody know of any (preferably open-source) REST frameworks for .NET that are worth checking out?
RESTful with many parameters?
by Tom Dyer,
Your message is awaiting moderation. Thank you for participating in the discussion.
How would you request a resource that was identified by a large set of parameters?
For example, I want a list of all the dependent/required products for a given set of products.
URI is /required_products/{43,555, .... very large set of product ids} And the resource identified is the list of required products for this set of products ids.
Seems like its GET but are there too many parameters needed to identify the resource?
Maybe a POST but a post is not safe, indempotent and is typically used to create a new resource, which the list of dependencies is not.
Perhaps a POST. But a POST is not "safe", it can have side effects, and is typically used for a resource update or for creating a new resource associated with the URI.
thanks,
very nice
by Nikita Ivanov,
Your message is awaiting moderation. Thank you for participating in the discussion.
One of the clearest REST articles I've read in a while... Thanks!
Nikita Ivanov.
GridGain - Grid Computing Made Simple
Re: RESTful with many parameters?
by Rafael de F. Ferreira,
Your message is awaiting moderation. Thank you for participating in the discussion.
I don't see why not use GET. HTTP doesn't prescribe an upper bound on the size of the URI.
Re: RESTful with many parameters?
by Tom Dyer,
Your message is awaiting moderation. Thank you for participating in the discussion.
I dunno, that kind of smells bad. I mean isn't the resource identifier, set of product ids here, just going to get too large at some point?
Wonder if the set of product id's aren't a resource that can be created, via POST, then it's identifier/URI can be used to GET the collection of dependent products.
Re: RESTful with many parameters?
by lipman li,
Your message is awaiting moderation. Thank you for participating in the discussion.
Unless you call get the very long URI within browser(browser does have the length limitation), it shall not be any problem to interact between applications provided the applications do not have length limitation on the get URL length. HTTP itself seems no length limitation.
Re: RESTful with many parameters?
by Kirstan Vandersluis,
Your message is awaiting moderation. Thank you for participating in the discussion.
I agree HTTP itself does not impose a limit, but I have experienced GET size limitations on a number of projects within browsers, typcially accessing XML-based resources with attached XSL stylesheets. If your calling clients are only other applications, it would seem that this would work. But another caution is that intermediaries might impose size restrictions (see for example: classicasp.aspfaq.com/forms/what-is-the-limit-o...).
I'd have to agree with Tom Dyer that the approach of stuffing an arbitrarily large list into the query string seems awkward. I think this situation fits Stefan's "exception criteria" from his article:
"...there are often reasons why one would violate a REST constraint, simply because every constraint induces some trade-off that might not be acceptable in a particular situation"
I certainly don't claim to be a REST expert, but in my opinion, I'd say a POST would be a better approach in this case.
Representations
by Jim Standley,
Your message is awaiting moderation. Thank you for participating in the discussion.
Is an editor a representation?
Is it ok to put representation on the URL?
I have done this recently:
/Repo/Element/101 <- returns HTML
/Repo/Element/101?json <- returns JSON
/Repo/Element/101?edit <- returns an edit page
Re: RESTful with many parameters?
by Tom Dyer,
Your message is awaiting moderation. Thank you for participating in the discussion.
I tend to agree with Kirstan and think I'd use a POST and not be so tied to the REST uniform interface for this case. Good point about possible intermediary limitations.
Also, I probably wouldn't get the caching benefits of GET because the same URI from this large set of URI's wouldn't be accessed that often. The resource would mostly likely not be a good caching canidate.
This is probably taking this to the absurd but can one use an executable artifact,( proc, code block, SQL select,...), as part of URI. The result of executing the block on the Resource server would be used to identify the resource.
Re: Representations
by Tom Dyer,
Your message is awaiting moderation. Thank you for participating in the discussion.
Yes, it's ok to put the representation on the URL. This is what Rails does and is suggested by the O'Reilly REST Web Services book.
"/Repo/Element/101?edit <- returns an edit page" is similar to the URI used in Rails for a form that will be filled in to update a resource.
Would be /Repo/Element/101/edit in rails.
Re: REST on .NET?
by Stefan Tilkov,
Your message is awaiting moderation. Thank you for participating in the discussion.
Ole, you might want to check out these postings:
www.infoq.com/news/2007/05/wcf-web-programming-...
and
www.infoq.com/news/2007/10/mindtouch-dream
HTH,
Stefan
Re: RESTful with many parameters?
by Stephan Schlöpke,
Your message is awaiting moderation. Thank you for participating in the discussion.
I think a better way to use this would be to have a sort of "search" or "query" you create. You could do a post on some URI like ./query/product_dep which would create a query resource. Now you "add" products to the query either by sending a product uri list with the initial post or by calling post on ./query/product_dep/{id}. With every post to the query resource the get on the query resource would change.
It is very similar with searching something with multiple parameters. In such a case it would be much easier to create a search resource and once created do a get on the created resource. And when done just send a delete to the created query resource.
There are multiple ways to solve this. However I think doing a GET on an URI and building the URI like ./something/{10,20,40 ...} on the client seems not right. It would require the client to have a detail knowledge of building the URIs while normaly the client should only follow links provided by the service.
Very nice articel stephan btw :-)
c# Interface analogy
by Maximilian Schulz,
Your message is awaiting moderation. Thank you for participating in the discussion.
Although it is a different analogy than Peter was referring to, I love the one about c# Interfaces. We have some hardcore c# guys here who I try to convince to give REST based services a try. And the Interface analogy is probably perfect to describe how it can be understood. I will give it a try next week during our end-of-year-team-meeting-and-evaluation. Anyways, REST is not that new to me, but I cannot wait to read the next part ;)
Re: RESTful with many parameters?
by Kirstan Vandersluis,
Your message is awaiting moderation. Thank you for participating in the discussion.
I think that creating and managing a "query set" object on the server side violates another RESTful criteria - operations should be stateless. I suppose you could take the view that a "query set" itself is an application object, with a URI as you mention. Then REST operations like PUT, GET, DELETE would make sense to manage the query set. Still seems a bit awkward though, for performance reasons if nothing else. If I'm querying for 100 items, that's 100 PUTs to my query set before I invoke the query. There should instead be an operation to send a query in one operation, and I think POST is just fine to do this.
Re: RESTful with many parameters?
by Stephan Schlöpke,
Your message is awaiting moderation. Thank you for participating in the discussion.
Actually there is no reason to PUT a list of query items in mutliple PUTs. If for instance you have 100 items to query why not just do a put to create a query resource sending all 100 items at once? And I wouldn't say it violates any RESTful criteria. Actually it is stateless since the state is persistent in the resource (in this case the query resource). And to my understanding that is the idea. Instead of using session states put the state into the Resource. And I see not really a difference to the POST. A PUT creates a resource and returns the link to the created resource. The resource created is the result of the query. And optionally PUT can return not only the new location but the content as well. So with one PUT you can get the result. Difference to POST is that you do not need to remember the result since with the location beeing changed to the resource you can just refresh the location and receive your result again (Or you can link it unless you delete the query right after you used it). Mostly you can do that with POST too but normaly you POST to a resource to update it. So the POST way would be a violation of the uniform interface definition I think. But I don't think the PUT/GET/DELETE is a violation.
Resource graph traversal is not the same as state transition
by Ganesh Prasad,
Your message is awaiting moderation. Thank you for participating in the discussion.
Stefan, great article. I understand and greatly respect the REST view of the world. However, I have found in my discussions with RESTafarians that there are some aspects that tend to be confusing, especially the terminology that tends to be used around the HATEOAS concept.
You said:
> There is an even more important aspect to the hypermedia principle — the “state” part of the application. In short, the fact that the server (or service provider, if you prefer) provides a set of links to the client (the service consumer) enables the client *to move the application from one state to the next by following a link*.
When you say the client "moves the application from one state to the next", I understand that to mean that updates are taking place. But if the client is merely traversing links (using a sequence of GETs, for example), then the application's state has not changed at all. What has changed is the client's view or representation of the application. The client has merely changed its perspective of the application's state and is looking at it from a different "angle", so to speak. In other words, the client is traversing the resource graph, which is a hyperlinked set of URIs representing resources.
We need to make a clear distinction between State Transitions (which most people would expect to only occur on updates), and mere link traversals, which change the client's view (representation) of the application but not its state.
If the HATEAOS model means link traversal when it talks about state transitions, then we really need to clean up the terminology, because it needlessly confuses non-RESTafarians.
Regards,
Ganesh
Re: Resource graph traversal is not the same as state transition
by Stephan Schlöpke,
Your message is awaiting moderation. Thank you for participating in the discussion.
You sure can do a state transition with resource traversal. For example you have a resource which is in the edit state and you edit it at someuri/resource/id now you get the link to someuri/resource/id?state=finish. When you follow that link the state changes on the resource is no longer editable. The state change you can call multiple times without ever returning with a different result. Now you wouldn't be given an edit link anymore and calling the old edit link to edit the resource would result in an illegal state result.
I think that this is a real state transition and I would say that it conforms to REST.
Re: RESTful with many parameters?
by Kirstan Vandersluis,
Your message is awaiting moderation. Thank you for participating in the discussion.
That seems viable, Stephan, to use a PUT as you describe, to load the entire query with one call instead of the 100 calls I previously stated. But I am still bothered a bit by state. You mention "The resource created is the result of the query". Initially, I thought we were discussing building up a query, storing the query as a resource (using PUT), then being able to reference that resource to invoke the query. Either way, whether you store the query or store its results, you have created session-specific data, and will need to consider its management. Do you rely on the client to DELETE it? What if they don't? Does it get removed with a session timeout? This session data is one thing REST attempts to avoid by recommending stateless interactions. So if we have to bend the rules and go outside the normal REST mode of operation, I would still opt to pass these large queries through a POST.
Re: RESTful with many parameters?
by Stephan Schlöpke,
Your message is awaiting moderation. Thank you for participating in the discussion.
I would in most cases only store the query in a database. I did this in a project recently. We store the query in the database and the client also submits a time to life. So if the client does not delete the query it gets removed later. That is the state stored in the resource rather than having a session management. A batch which for example checks once an hour removes all entries in the database which are outdated. Idially the client sends a DELETE when the result resource is no longer needed.
It is like in real life. I have a guy in my office called Archie. He is responsible to gain documents from the libray whenever someone needs it. Once I have a request for a couple of documents I hand him a list what to get. Now I can just wait until he got everything in order to take it with me. Or I go back into my office waiting for an email that he has gathered all my documents for me to pick up.
In a service designed like that I create a list which is my query request. I do a PUT to archie so he has the newly created list. The receipt I get is an URI where I can get my documents once they are collected. In the normal case they are instantly available so I just do a GET on the resource and have my result. In various situations a backend needs more time to gather the documents together which may take a couple of minutes. This gives me as a client the option to inform the user that his request is beeing processed. Once the request is processed the user can see the result. Or if it is a real long request a mail is send to the user with the URI link where to get the result.
Since Archie wants his documents back he keeps the list until I am done with the documents. Once I am done I return the documents and get the list back or the list gets destroyed. This is where the client puts the DELETE to the result. Once he or she is done with it.
The good thing in it is that if you execute the query and stores the result it is totally independend from someone deleting or adding entries to the database. Those the result I see dosnt change while I am working with it. This can be of benefit especially when you do a search. If you send the link result to another person he or she can open it and the 4th entry is the same you saw. In some cases it might be better to store the query and the first get removes it. This however is not REST conform I think since the GET I can only execute once.
Executing a DELETE with the option of a timeout and a clean up task is I think the best way to go. In such a case the client has the chance to work with the result resource as long as he wants without having to store it. Also this way it is easy to cache such a resource while with POST you cannot cache the resource in a proxy since the proxy dosn't know in what relationship the posted content to the result is.
Re: Resource graph traversal is not the same as state transition
by Stefan Tilkov,
Your message is awaiting moderation. Thank you for participating in the discussion.
Ganesh, you write
There is resource state and application state, and I agree the traversal of a link by the client via GET does not change the resource state. But it changes the application state, as the client is now "looking at" or "holding on to" a different representation which includes different links than the one before. Application state is thus kept on the client (which means the server doesn't care about it). But the representations sent from the server to the client "drives" it because they contain or do not contain links to specific other resources.
"Hypermedia as the engine of application state" is both the least understood and the most powerful aspect of REST, which is why we have an article just about this coming up soon.
What when REST semantics are not enough?
by Gael Fraiteur,
Your message is awaiting moderation. Thank you for participating in the discussion.
It seems like REST semantics are identical to CRUD ones: Create, Update, Delete. It forces each resource to have a very simple state diagram: a start node with a CREATE transition, then a unique normal node with an UPDATE transition, looping back to itself, and a DELETE transition, going to the terminal node. This is a pretty simplistic representation of the state of a resource.
What is we want to have a richer state diagram? Take the example of an order, how to represent the transition from the state "booked" to "shipped" (this is a parameterless transition). And how to represent the transition to the state "cancelled", when we want to add the reason cancellation (transition with one parameter).
Object-oriented methologies have learned us how to deal with these situations using procedures/methods, but what would be the right approach using REST?
Excellent
by Sadek Drobi,
Your message is awaiting moderation. Thank you for participating in the discussion.
Great article Stefan, waiting for the next!
Re: RESTful with many parameters?
by Ally Kendall,
Your message is awaiting moderation. Thank you for participating in the discussion.
I would use indirection. I.e. I would give it a shorter name, such as a hash of the parameters.
Re: What when REST semantics are not enough?
by Ally Kendall,
Your message is awaiting moderation. Thank you for participating in the discussion.
These are updates, which are POSTs. In OO terms, the method specifier is always a parameter of a POST.
Re: What when REST semantics are not enough?
by Stefan Tilkov,
Your message is awaiting moderation. Thank you for participating in the discussion.
There are multiple options: one is to PUT a new state to the resource, effectively changing its internal e.g. from booked to shipped. Another way is to do a logical move of the resource from one collection (of booked orders) to another (of shipped orders). A third way is to represent the state change as a resource in itself, e.g. by POSTing it to the order where it becomes a sub-resource. This way, you have a history of changes.
The mapping to CRUD is not 1:1 -- a POST can create new resources, or simply process something and return a result. In case a POST is used to create a new resource, the server chooses the URI. A PUT can be used when the URI of the resource one wants to affect is known -- it will either create or update a resource there.
Re: Love the analogy
by Mike Glendinning,
Your message is awaiting moderation. Thank you for participating in the discussion.
Of course in the real world, where confidentiality and privacy of customer information is important, implementing a "small door with a key" is often a good idea! Just ask the UK government after their recent loss of personal banking details for 25 million citizens :-)
In fact this is one of the interesting tensions in the design of web-based hypermedia applications: The more we make data accessible through URIs and hyperlinks, the harder it becomes to secure and control access. This problem is exacerbated by the crude security framework of HTTP.
In the world of "enterprise applications" the norm has been for years to design systems that strictly control access to data. This is in line with the design and operation of our organisations, but contrasts markedly with the web where the goal has always been to *provide* access to data. It has also lead to a whole new industry for enterprise data warehousing and business intelligence solutions that "unlock" hidden data.
If REST is to "take over" for enterprise applications, I suggest it's going to have to address issues of data security much more seriously. The long term effects on our enterprise architecture might be quite interesting, nonetheless.
Re: Resource graph traversal is not the same as state transition
by Ganesh Prasad,
Your message is awaiting moderation. Thank you for participating in the discussion.
Stefan Tilkov said:
Ah, that explains everything! In my terminology, there's "client state" and "application state". You call them "application state" and "resource state". Fair enough!
This ties in neatly with our model SOFEA (Service-Oriented Front-End Architecture), where client state is managed on the client, and a controller on the client side interacts with services (either SOAP or REST) to drive what we call "Presentation Flow". Obviously, client state and Presentation Flow are constrained by the representations that the service tier exposes.
I think it's important to clarify that SOAP-based Web Services also expose *representations* of behaviour, because these do not simply mirror methods on Domain Objects. Unlike with REST-based "services", client state is not directly constrained by SOAP-based web services. Because of its nature as a verb-oriented view of a domain (rather than a noun-oriented view that is REST), either a whole process has to be encapsulated in a single operation (implemented by WS-BPEL) for the client to consume, or the client has to define a bespoke process using the set of services available. This is not necessarily a disadvantage. It's just a different model.
Regards,
Ganesh
Architecture of resources ?
by Vladimir Vacula,
Your message is awaiting moderation. Thank you for participating in the discussion.
Great article Stefan. I was thinking about your example with resources. You presented resources :
- "/orders" and "/orders/{id}"
- "/customers" and "/customers/{id}"
- "/customers/{id}/orders"
what if i don't want to categorize object in URI-name of resources. What if "id" means just a document without identification, if document is an order or customer card?
Let's say i have resources :
- "/document/{id}" (which implement GET of details and POST of new documents)
- "/search" (which returns list and implement POST of restricting conditions i.e. "category:customer" or more complex "category:customer, category_id:123, relation:orders" )
Is it better to use categories in URI of resources (like "/orders") instead of creating general resources (like "/search")? Is there any recommendation which way is better and why? And finally, what if "/orders" returns really huge list? In "/search" i could implement condition i.e. "last:10", "max_date:2006-12-31". How to handle this issue in case i use resource "/orders" ?
Thanks
Re: Architecture of resources ?
by Stefan Tilkov,
Your message is awaiting moderation. Thank you for participating in the discussion.
Hi Vladimir,
First of all, the characters that make up a URI are much less important than one may think. But anway, I prefer to give resources meaningful names -- but this is just a design decision. Your document/{id} example would mean that a POST to it would be handled the same way, regardless of whether it's an order or customer, unless you switch on the content type. If handling both similarly -- e.g. if you just want to store a new document without looking at its contents -- is what you want, this seems perfectly fine.
I suggest to implement searches as GETs, not POSTs -- it's useful to be able to link to a search result, and it's a meaningful resource in itself -- "the list of all customers named Smith" qualifies as a resource from my POV.
Regarding the large lists, one way is to redirect a request to /orders to /orders?offset=0&count=10 and include a link to /orders?offset=10&count=10 -- i.e., the indivual pages become resources in themselves.
HTH,
Stefan
Re: Love the analogy
by Felipe Nascimento,
Your message is awaiting moderation. Thank you for participating in the discussion.
Great article.
Do you suggest any material about REST security we can take a look at? If application does not hold state, how to check if some client application has the authority to access one resource? Should the client application pass in the credentials in every request? Should the RESTful application has a security service that would return a session ID that would be used by the client application in every subsequent requests?
Tks
Felipe
Re: Love the analogy
by Stefan Tilkov,
Your message is awaiting moderation. Thank you for participating in the discussion.
Thanks Felipe. Yes, both sending the credentials with every request (the way HTTP Basic Auth does things) and sending a security token (similar to Google's WebAuth) are fine. I will take up REST security as another topic to cover - not necessarily by myself.
Re: RESTful with many parameters?
by Torben Wölm,
Your message is awaiting moderation. Thank you for participating in the discussion.
You could also use custom http-headers for your many parameters...
Understanding the Difference!
by William Martinez,
Your message is awaiting moderation. Thank you for participating in the discussion.
Stefan, totally agree with your claim. Most of the discussion I've had in the past relates to the confusion of all those four things. For some, Web Services are just a way to distribute object (thus a WS is an exposed object!), some others cannot imaging WS as a messaging thing: it is just an exposed method (RPC). Even more, some see on REST a simpler WS, which is not. I mean REST is much more that just WS, and WS can be implemented using REST philosophy. In fact, WS architecture's resource view is totally compatible with REST.
But to understand this, you need a "mind shift", totally true.
So IOW, this applies only to web projects. What about Windows projects?
by Parimal Jisaheb,
Your message is awaiting moderation. Thank you for participating in the discussion.
So IOW, this applies only to web projects. What about Windows projects?
Re: So IOW, this applies only to web projects. What about Windows projects?
by Stefan Tilkov,
Your message is awaiting moderation. Thank you for participating in the discussion.
If I understand your question correctly: no, this does not only apply to projects that use an HTML UI - you could have your rich client communicate with your server using HTTP according to REST principles.
Thanks
by Yuen Chi Lian,
Your message is awaiting moderation. Thank you for participating in the discussion.
This article has definitely helped me to form a clearer picture about REST and its fundamental.
Cheers,
yc
Re: Architecture of resources ?
by Mike S,
Your message is awaiting moderation. Thank you for participating in the discussion.
A bit off topic but this post reminded me of one project which might be of interest to the poster.
On topic though totally agree with Stefan's response. Search should be exposed as GET-able URI which effectively creates unlimited list of resources which are search results. Just a slight addition to the pagination solution: I think it is better be done the same way content negotiation is, that is GET /orders would return same representation as /orders?offset=0&count=10 mentioning the latter as Location header so that the client can cache the result against the proper key. Interestingly the spec talks about Location header as the target for redirection :).
Re: What when REST semantics are not enough?
by Mike Schinkel,
Your message is awaiting moderation. Thank you for participating in the discussion.
Actually, in a RESTful design PUT is used for UPDATE (only) or INSERT (when the client determines the resource URI) and POST can be used to INSERT or various other processes.
Re: RESTful with many parameters?
by Mike Schinkel,
Your message is awaiting moderation. Thank you for participating in the discussion.
POST is part of REST's uniform interface. For HTTP, that uniform interface is generally considered to be GET, PUT, POST, DELETE, and HEAD although it can include a few other like PATCH.
And since REST is an architecture style it could be used with a different request/response protocol and with a different uniform methods although that's just a point to clarify the though process as few people are using REST outside HTTP.
Re: Love the analogy
by Mike Schinkel,
Your message is awaiting moderation. Thank you for participating in the discussion.
The type of security concerns you mention are a red-herring. RESTful apps can be fulled secured with SSL on top of HTTP security. Or do you view SSL as not being sufficient and if so, why?
Re: Resource graph traversal is not the same as state transition
by Mike Schinkel,
Your message is awaiting moderation. Thank you for participating in the discussion.
Actually, the term "representation" is a defined term in the context of REST as per the W3C's Architecture of the World Wide Web, Volume One as opposed to your colloquial use of the term related to SOAP. And the fact that the client has an effectively infinite potential number of operations to know and understand in SOAP as opposed to the tight contrained number of operations is one of the key advantages of REST.
Consider REST like the physical compatibility of the plug on your computer's power cord and the electrical outlet where your computer gets its power. REST's constraint on verbs is like the plug/outlet's physical compatibility contraint. Conversely imagine having every power cord had a different type of plug; that is SOAP and all its operations! Actually if you travel a lot internationally, you already know what a nightmare of inefficiency and lack of capability that lack of conformity can produce.
Re: Architecture of resources ?
by Mike Schinkel,
Your message is awaiting moderation. Thank you for participating in the discussion.
Also to Stefan's reply, your proposed "/search" is stated as a verb and for REST you should use a noun if for no other reason that it puts you in the RESTful frame of mind.
In the "customer" cases you mention I'd say use "/customers" and "/customers/123/orders"
After all you can think of a URL as just a generalized query mechanism in many ways. The URL is really supposed to be an opaque string but because of web server implementations many of us have been conditioned to think of URLs are being directories and filename, even in the case of dynamic output from such as .jsp, .php, .aspx, etc. The URL really should just represent the resource whose representation it returns when dereferenced and hide how the representation is prepared on the server as the client really doesn't need to know. There is no need for a special "search" metaphor.
So for your latter "order" cases, you can use "/orders/last10" and "/orders/thru-2006-12-31" or if you just call "/orders" use paging as Stefan suggested.
Re: So IOW, this applies only to web projects. What about Windows projects?
by Mike Schinkel,
Your message is awaiting moderation. Thank you for participating in the discussion.
Exactly, and I think there would be huge benefit to building "RESTful" desktop applications using OOP objects that all descended from a base class of "Resource" as in Stefan's example. If I had time to play with this I'd love to create such a framework.
Re: So IOW, this applies only to web projects. What about Windows projects?
by Florian Schwarz,
Your message is awaiting moderation. Thank you for participating in the discussion.
What about the Restlet project (www.restlet.org/)? It's focus is on Web development but it can also be used for desktop applications. All of it's core classes subclass the 'Uniform' class, which represents a uniform interface with the HTTP methods GET, PUT, POST etc.
Question about use of Cookies
by Matthias K.,
Your message is awaiting moderation. Thank you for participating in the discussion.
On several occasions I have read that using Cookies would violate the REST principle of stateless interaction. I don't really see why this is necessarily true.
As far as I understand, the demand for stateless communication only concerns the state of resources, and not client or application state. However, the most typical use of a cookie, namely storing user preferences or session data, does for one not concern resource state, but application or client state.
Second, all required session data can be carried around in the cookie itself, and not just be stored in the server memory identifyable be a session key (as is the case with e.g. Servlets). In other words, I do not see where the mere use of cookies does not harm server scalability and reliability, if used properly.
That being said, what are your thoughts about the use of cookies in a RESTful application? Am I missing something?
Re: Question about use of Cookies
by Stefan Tilkov,
Your message is awaiting moderation. Thank you for participating in the discussion.
I don't think you are missing anything. In my opinion, cookies themselves don't violate REST principles. Using cookies to store a key that identifies an entry in a server-side session state data structure does.
Re: Question about use of Cookies
by m k,
Your message is awaiting moderation. Thank you for participating in the discussion.
I would follow the last comment up by saying that a cookie may hold a server-side session id, but the session id itself can also be something exposed in a RESTful way. For example, a cookie value could be example.com/sessions/12345. Taken by itself, isn't a server-side session just another resource (or noun), except perhaps that its guts are only exposed internally to application(s) requiring a session?
RESTful transaction service
by Ian Goldsmith,
Your message is awaiting moderation. Thank you for participating in the discussion.
I'm beginning to get a grasp of REST principles and contraints, but am struggling with one particular example.
I'm trying to model a service that manages checking accounts, providing some very basic capabilities. The basic resource is an account, which has an id and a set of attributes. This is easy to model:
GET <host>/accounts - will return an XML doc listing all the accounts as REST resources e.g. <host>/accounts/{accountid}.
GET <host>/accounts/{accountid} will return an XML document that lists all the attributes (for now lets assume the only attribute is the balance of the account).
What I want to create is a set of methods for "withdraw", "deposit", and "transfer". Clearly I could create these using documents for each method and POST them to the account, e.g.:
POST <host>/accounts/{accountid}
<withdraw>
<funds>{value}</funds>
</withdraw>
This doesn't seem to follow the REST contraint of using a common set of methods though. To be more RESTful, I guess I would have to PUT a new balance value to the account (at least this would be idempotent), but this gets clumsy quickly, especially for transfer, given the different authorization levels required (it's easy to see a case where I would have different authorization levels for deposit and withdraw for example).
Am I missing something obvious? Is there an easy way to implement this type of service?
Thanks in advance,
Ian</host></host></host></host>
Re: RESTful transaction service
by Stefan Tilkov,
Your message is awaiting moderation. Thank you for participating in the discussion.
Ian, you might want to think about modeling the (trans)actions you describe as resources in their own right. E.g. you could create a new transaction via POST, get back the URI in a Location header, and then PUT the state information (including from where to withdraw and where to deposit).
Re: RESTful transaction service
by Mark Little,
Your message is awaiting moderation. Thank you for participating in the discussion.
I mentioned in my presentation at QCon London that we (HP) did some work on RESTful transactions back in 2000. Well the specification still exists and if I ever find time I'm intending to re-implement it on RESTeasy. I'd be glad to discuss this if you're interested.
Send large result set
by John John,
Your message is awaiting moderation. Thank you for participating in the discussion.
hi all,
do you have any idea how to send large result sets?
request:
GET /user
server returns 10 000 records with links. It is bad practise to return all records to user. I think one of the solution can be: send to user "HTTP/1.1 303 See Other" response and to location header set domain.com/user?range=100,1000, which means that resource contains records from 100 to 1000. Does anybody have idea how to solve this problem ? It is good to solve it with 303 status code?
thx..
Do you suppose that all possible actions can be reduced to 4 verbs?
by Mark Kamoski,
Your message is awaiting moderation. Thank you for participating in the discussion.
Do you suppose that all possible actions can be reduced to 4 verbs?
Use of Accept to define required representation
by Martin Haigh,
Your message is awaiting moderation. Thank you for participating in the discussion.
I also think this is a great introduction to REST, thanks. I am however struggling with the use of the request Accept header to define the representation required. The Accept header defines the Content-Types that are acceptable and is often a list. Whilst this header could be specifically set by a custom client, somthing like a browser defines a list of values (often 3 or more). Would in not be better to have the representation required defined in the URL as part of the ID for example (../customer123.pdf). That way a user could explictely point their browser at an HTML, SVG, PDF, etc represention as they wanted?
Re: Use of Accept to define required representation
by Stefan Tilkov,
Your message is awaiting moderation. Thank you for participating in the discussion.
Martin, you can do either or both - it's entirely acceptable to do both content negotiation and have additional, explicit resources in case you want to be able to link to specific representations.
Rest URI design with URL parameters
by Thomas Tkac,
Your message is awaiting moderation. Thank you for participating in the discussion.
Hi,
I designig REST web APP and I want to apply some operations on resource op1, op2, op3 which have one or two arguments.
I want to apply this operations in one request
sample:
GET /resource?op1=name&op1=name2&op2=aa,bb&op1=name3
in order which is in request
at first op1 then op1, op2 op1 with arguments (values)
Is this good practise or do you have any suggestion recommendation how to solve this problem?
thx
UML Diagrams
by Ersoy Hasanoglu,
Your message is awaiting moderation. Thank you for participating in the discussion.
In which application you drew those beautifull UML diagrams?
Re: UML Diagrams
by Stefan Tilkov,
Your message is awaiting moderation. Thank you for participating in the discussion.
Ersoy, I can't imagine you're still interested in an answer. But if you are: It was OmniGraffle on Mac OS X.
Re: UML Diagrams
by Ersoy Hasanoglu,
Your message is awaiting moderation. Thank you for participating in the discussion.
Much appreciated. Thank you Stefan.
Kind regards.
Re: UML Diagrams
by peng zhang,
Your message is awaiting moderation. Thank you for participating in the discussion.
Nobody Understands REST or HTTP, Please refer blog.steveklabnik.com/2011/07/03/nobody-underst...
and www.mfrbee.com/trade/
Re: REST on .NET?
by Vlad Bezden,
Your message is awaiting moderation. Thank you for participating in the discussion.
Ole,
If you still looking at .NET REST framework, I would recommend WCF Web API. Very nice and clean framework, the one I like most from all previous MS implementations.
well writen, and very easy to understand!
by phoenix bai,
Your message is awaiting moderation. Thank you for participating in the discussion.
thanks for the brilliant piece!
REST & standard behavior
by Dan Noonen,
Your message is awaiting moderation. Thank you for participating in the discussion.
I have a question about the word "standard" in reference to REST & RESTful HTTP. As a backdrop for the question, consider all of the apparently valid approaches suggested in the context of the "RESTful with many parameters" question. If the world of REST and RESTful HTTP provide many different options to achieve the same goal, won't we continue to find ourselves in a situation where a bunch of server specific logic gets coded into clients. "I know that for this site I need to do it THIS RESTful way in order to make the right thing happen and for that site I need to do it THAT RESTful way". This doesn't feel much different to me than SOA and the plethora of service specific interface logic one has to code against when dealing in that space. What's the benefit of using a few standard commands like GET, POST, etc. when you still have to wind down to managing server specific constructs in order to achieve anything meaningful?
I'm guessing I haven't made that mind-shift that's mentioned just yet & I'm hoping some replies will help.
Re: well writen, and very easy to understand!
by Stefan Tilkov,
Your message is awaiting moderation. Thank you for participating in the discussion.
Thanks, much appreciated.
Thank you for a clear explanation
by Anuradha Va,
Your message is awaiting moderation. Thank you for participating in the discussion.
Thanks. It would have been nice to get such clear explanations for every concept that one needs to be aware of.