Learn REST: A Tutorial

http://rest.elkstein.org/

by parenthesis • 15 years ago

126 52 15 years ago

rest.elkstein.org

gte910h3• 15 years ago

>Rather than letting clients construct URLs for additional actions, include the actual URLs with REST responses. For example, a "product list" request could return an ID per product, and the specification says that you should use http://www.acme.com/product/PRODUCT_ID to get additional details. That's bad design. Rather, the response should include the actual URL with each item: http://www.acme.com/product/001263, etc. Yes, this means that the output is larger. But it also means that you can easily direct clients to new URLs as needed, without requiring a change in client code.

This a thousand times yes.

jwingy3• 15 years ago

If you have your routes designated in a central area , this shouldn't be a problem anyways right? In fact, you need to designate this someplace anyways, whether it's on your server (in the database or in some code), or on the client-side code.

I might be missing something here though or just not quite understanding the problem.....

masklinn3• 15 years ago

> If you have your routes designated in a central area , this shouldn't be a problem anyways right?

It's not a problem for the server (and even then, it might be: what if the root handler simply sends to further sub-handlers after just chopping off part of the URL or query arguments? There isn't necessarily a central URL authority on the servier either), but generally is one for the client: in a truly RESTful system, the client knows one URL and one only (the service's root).

It also knows all the media types the service can return (which is why meaningful content-types, as those returned by Github, are great).

From this, it can traverse the service to the place it needs, and it may cache URLs along the way (for more efficient traversals later on) but those URLs may die altogether and require a re-traversal.

This scenario is built into the architectural style.

> In fact, you need to designate this someplace anyways, whether it's on your server (in the database or in some code), or on the client-side code.

If URLs are designated anywhere in the client-side code (outside of the root service URL and a URL cache, which is accumulated knowledge rather than built-in), it's not a RESTful service, it's RPC-over-HTTP.

gte910h3• 15 years ago

If you use URLs instead of IDs, that central area moves from the client to the server.

Having worked with both types, the URL type REST is far far easier to write clients for.

nikcub2• 15 years ago

If you are using backbone or another js framework, rip out the url() routines so that sync will then use the url from the model.

I did this in all of my code and it works very well.

stiff• 15 years ago

If people would simply advocate building applications which follow the semantics of HTTP instead of advocating "REST", many more people would understand the benefits and conform; there would be no need to write a thousand and one posts explaining what is REST. Unfortunately the original exposition of this way of building web applications was done in a dissertation, in a "scientific" style that I think Orwell captured so well (http://www.mtholyoke.edu/acad/intrel/orwell46.htm, worth a subscription of its own). Another problem is that unfortunately most web developers (not to mention "SEO experts") don't have any real understanding of HTTP or the principles behind the WWW, which makes them also unaware of the very practical problems certain design decisions can cause.

postfuturist• 15 years ago

An article describing rest should link to rfc2616 which actually has quite a bit to say about using HTTP and REST (without ever using that term). http://tools.ietf.org/html/rfc2616

kragen• 15 years ago

It seems to me that if you want to learn REST, you'd be better off reading Roy's dissertation, which is pretty short and doesn't contain bullshit like, "Thus, REST uses HTTP for all four CRUD (Create/Read/Update/Delete) operations."

masklinn3• 15 years ago

I'd recommend reading his blog instead, especially his analysis of services claiming RESTfullness. The thesis is not exactly clear, and I did not grasp the significance of what's now called "HATEOAS", the importance of media types and the lack of importance of URLs (as well as the complete irrelevance of "pretty" URLs to the restfullness of a service) until I read his blog posts on the subject.

glenjamin3• 15 years ago

One thing I've always struggled with with REST, is how you should handle additional verbs.

As a contrived example, say we have a booking

    GET /booking/:id

And we then want to cancel this booking, more specifically we want to trigger the "cancel" action (transition), which would change the state of the booking from "active" to "cancelled". There are a few possible ways to do this, and I'm not really sure which is "correct" for REST, or whether it actually matters:

    POST /cancel (booking = /booking/:id)
    PUT /booking/:id (state = cancelled, note this is dictating the resulting state, not the transition)
    POST /booking/:id/cancel
    CANCEL /booking/:id (custom verb, good/bad ?)

hammerdr• 15 years ago

POST /cancellation { :booking_id => 123 }

In general, it is not wrong to noun-ify domain concepts such as a cancellation.

tantalor• 15 years ago

But only if its a Java application.

glenjamin3• 15 years ago

I can see why this would be the case given the constrains imposed by the the REST architecture, but I don't really see what benefits this has over having some sort of "cancel" action to be performed on the booking resource.

Sidenote: Is it "better" to pass booking_id = number, or booking = booking resource URL. Why?

rfrey• 15 years ago

DELETE /booking/:id {reason=cancellation} ?

bodhi5• 15 years ago

It would really depend on the semantics of the booking and the system. Another alternative would be

    DELETE /booking/:id

Which is basically a more correct HTTP version of your last option. Otherwise, I would lean towards your second option (the PUT), as I would think that what you are doing is telling the server what you want the state of the booking to become. What happens server-side based on the PUT isn't really your concern as a client of the API.

> more specifically we want to trigger the "cancel" action

I'd posit that this is actually something that the API user shouldn't need to care about.

Good question though, I've often pondered it myself.

artsrc4• 15 years ago

I think that a canceled booking is still a booking, just a cancelled one.

Here is wording from the HTTP spec "However, the server SHOULD NOT indicate success unless, at the time the response is given, it intends to delete the resource or move it to an inaccessible location. "

I don't expect the server to move the booking to an inaccessible location so I see this as a state change not a delete. Hence I am thinking PUT, not DELETE.

jtchang• 15 years ago

The resource you are changing is the booking resource identified by

/booking/:id

I would go with PUT /booking/:id with a status of canceled.

This makes sense to me because of the semantics of traditional FSM.

You are going from some state (active) to (cancelled). You are not dictating the resulting state, only that you would like to set the status to cancelled.

PUT can return an error in which case the transition failed. It can return success and the transition is good.

glenjamin3• 15 years ago

This is exactly dictating the resulting state. Consider the FSM:

    States = (active, cancelled);
    Transitions = [("cancel", active -> cancelled)]

If the API says PUT status = cancelled, then we'd look through the transitions and find the one that matches our current state and the target state ("cancel"), then execute the associated code, the side effects of this transition - probably sending an email.

We now want to refactor the cancellation model to this:

    States = (active, cancellation requested, cancelled)
    Transitions = [("cancel", active -> cancellation requested),
                   ("confirm", cancellation requested -> cancelled)]

You can see where I'm going with this already, the transition we want the user to take from the active state is the same, but the additional state means that we either have to change the API for cancellation, or have the PUT status do something other than specify the state we're moving to.

This is the reason I firmly believe changes of state should be requested by naming the transition, and why I'm not entirely sold on the "best" way to do this with a "proper" RESTful architecture.

pyrhho• 15 years ago

May as well weigh in. How about:

    POST /booking/:id/cancellation

Because you are creating a 'cancellation object' belonging to that booking.

Ninja Edit: Really it is about being consistent, and predictable, so that people using your API can guess how it will act. If you are using an API of yours, and can't guess what the correct url/method is, you should change the API. (I forget who said that)

nikcub2• 15 years ago

You should fall back on thinking about what you are doing to the record in the database.

You are updating the state field (ie UPDATE bookings set status='cancelled' where ID=:id) which maps to PUT

jebblue2• 15 years ago

The real focus for web services needs to return to SOAP. SOAP is a truly contractual design that solvs many of the problems that have to be solved by hand in REST, do we use JSON or what to transfer the data? How about argument types? REST is like a nice way to express HTTP other than that SOAP was designed to and solves web service problems very well.

icebraining2• 15 years ago

(I find it very distasteful to downvote parent's comment without replying. It's a valid opinion, not a troll)

You're right that REST doesn't provide everything SOAP does, because SOAP is a specific protocol and REST is just an architectural style. On the other hand, there are already specific protocols to achieve that in a REST style (and reusing HTTP), like WADL.

Furthermore, it's not clear that a one-size-fits-all approach like SOAP takes is the right way. XML is great for some use cases but not others; by pigeonholing everything to it you create inefficient systems filled with hacks to avoid its shortcomings in certain domains.

SOAP in particular seems very strict, while REST based systems - particularly the Web - are designed to make an heterogeneous mix of decoupled services and clients work well together. The idea that a client should break if the schema changes, for example, leads to very brittle systems.

jebblue2• 15 years ago

>> The idea that a client should break if the schema changes, for example, leads to very brittle systems.

Thanks for that, much appreciated.

>> The idea that a client should break if the schema changes, for example, leads to very brittle systems.

That's the point, imagine building the web using string values instead of constants. With constants, if it changes, you immediately get notification from the IDE via the compiler and can fix it straight away. If it's a string, then it's up to the poor testers to find it and good luck, it has to be in a known use case.

I think for general communications REST is better than not following any standard by far. For web services though, my money is still on SOAP and I'm a Java/Linux lover not .NET these days, SOAP is still best for Web Services in my view.

emperorpenguin6• 15 years ago

Can somebody explain in one sentence why is REST a good thing? What does it bring to the party? Why is forcing every RPC call that my application makes into CRUDdable objects necessarily a good thing?

Frankly, I can't believe the amount of near-religious attention it's being given. You're taking an obscure aspect of HTTP (already a mind-bendingly terrible protocol in its own right) - verbs - and making it the cornerstone of your application framework.

sambeau3• 15 years ago

REST is stateless .: is cacheable

bodhi5• 15 years ago

> [HTTP is] a mind-bendingly terrible protocol in its own right

Could you detail your thoughts on this? The more I work with HTTP, the more I get impressed with how usable it is. Granted, it's not suited for some domains...

emperorpenguin6• 15 years ago

Ok, I'm being somewhat unfair. HTTP is an adequate (although overly-complex) protocol for simple document retrieval. It is unfortunate, (in my opinion), that we've used it in a whole ton of ways for which it was never intended.

Have you considered some of the hacks that we have to use to make HTTP do what we want? Comet/longpoll? JSONP? Have you looked at the bajillion different ways in which browsers and proxies fail to implement caching in a consistent manner? How browsers will only allow a limited number of concurrent connections to a particular host? Have you looked at a x-www-form-urlencoded post? Do you think that's a good way to send data around?

Anyway, I'm not really after a big discussion of HTTP's merits - my apologies for excessive opinionation. I am, however, interested in why so many people think REST is a magic bullet.

artsrc4• 15 years ago

REST facilitates loose coupling between clients and servers, scalability, caching, retrys etc. REST is a good thing because it provides the right abstractions for some applications.

A slow, unreliable interaction with a remote server is different than an interaction with an in process function call.

If ignoring this complexity is causing no problems then concentrate on what does cause you problems, then just learn enough about REST to recognize a problem in the future.

emperorpenguin6• 15 years ago

But how does REST improve scalability, caching, retrys, etc... over ANY other HTTP-request based scheme?

arturnt• 15 years ago

REST != HTTP. HTTP, which is the language of the web is just an example of a REST implementation. A lot of people get this wrong. This should say Restful for everything, not REST.

Also to be REST compliant you have to employ discoverability and hypermedia.

Read: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte... http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm

sambeau3• 15 years ago

This is missing a few salient points:

1) REST is not suited to complex multi-variable queries or transactions

2) REST should be a stateless transaction

3) REST read results should be cacheable

4) REST can use headers to specify content-type/mime-type

REST is not a suitable replacement for all client-server interactions e.g. complex, sql-like queries over many variables. It is best suited to URL-like queries that produce singleton docs or lists of doc IDs.

REST in its most common form is a protocol over HTTP and thus can (and should) take advantage of HTTP's methods to provide CRUD:

  Create  = POST
  Read    = GET
  Update  = PUT (although POST is fine)
  Delete  = DELETE

This negates the need for:

  /story/395/delete

  /delete/story/395

instead use

  /story/395

and send it a DELETE method.

bodhi5• 15 years ago

For the sake of debate:

> REST is not suited to complex multi-variable queries or transactions

Would it not be possible to represent a query or transaction as a resource, that you could GET/PUT like any other?

> REST should be a stateless transaction

I think there's a small grey area here around "stateless transaction". The HTTP request/response itself should be atomic (to be a bit loose with terminology), but the result can change the state of the system.

So the communication between client and server is the part of the system that is stateless. (Apologies if this was your intended meaning.)

sambeau3• 15 years ago

The HTTP request/response itself should be atomic

One of the great advantages of REST is that makes data caching easy. Statelessness is a requirement for caching.

"Would it not be possible to represent a query or transaction as a resource"

Anything's possible just about but the whole point of REST is to create uniform resource locators for data. The problem with creating rather forced complicated URIs is that you quickly lose uniqueness: the same data will start being represented by more than one URI and therefore will start to be cached a multiple of times leading to conflicts.

clark-kent• 15 years ago

This seems like REST tutorial for SOAP users. I would have liked it if they just described REST. Not always comparing it to SOAP.

extension• 15 years ago

In many ways, the World Wide Web itself, based on HTTP, can be viewed as a REST-based architecture.

In every way, the WWW is a REST-based architecture. REST is an analysis of the web, as it existed at the time. There is no more perfect exemplar of REST.

This is a crucial point. Fielding's paper is about how and why the web works. It's not, per se, about how the web should be used to make network services, though many have tried to derive that from it.

schiptsov• 15 years ago

There are two big ideas in REST. First one is in realm of system engineering, and second one in the realm of programming paradigms.

Using HTTP[S] protocol allows you to pass through almost every heterogeneous network. That means any highly restricted and protected (I prefer the term 'misconfigured') network of a cell phone provider, who blocks everything else, but http.

You can survive in that crazy hotel's or airport's wi-fi network, especially located in developing countries, which is a mess of cheap Chinese ADSL-modems and no-name Wi-Fi access-points with settings no one cares about.

It also means that you can pass through all these almost useless corporate firewalls made by idiots (why firewall if you have all those windows with IE6 boxes running by users with admin rights?).

The second big thing is about statelessness and using URI as a namespace - representing data as a file-system hierarchy and using one standard protocol everywhere - it is almost the same ideas which lays on the foundation of this enlightening Plan9 system. No xml, no BS, just names and simple standard protocol - 9P.

Together, those two ideas are enough to forget about all that proprietary crap, not because it is proprietary, but because REST is more general, flexible and easy to implement concept.

lhnz• 15 years ago

What happens when you need to request some data and therefore use the GET method, but also are passing sensitive data in the query? Should you use POST in this case in order that the sensitive request is not logged?

Learn REST: A Tutorial

Related Stories