4 ms·

In the PDF he points out it says "Resource names should be nouns—avoid verbs as resource names. It makes things more clear. Use the HTTP methods to specify the

• aaronem 13y ago
  The whole idea behind REST resources, though, is that the HTTP method expresses the action, and the URI identifies the object acted upon. In that conceptual scheme, there is neither need nor place for verbs in the URI; POST /topics/add is redundant, because POSTing to a collection already has the semantic value of "add an item to this collection". Similarly, if you're modifying an existing item, you don't need to PUT /topics/23/edit or what-have-you; PUT already means "replace the existing content with the request body I'm sending", so all else that's required is to identify the particular content to replace, for which /topics/23 suffices. Having the HTTP method and the endpoint gives you all the clarity you need in terms of what a request does, and to which thing it does it. An additional, and very non-trivial, benefit of this scheme is that it is standard and discoverable: "standard", in the sense that these basic HTTP operations are defined in RFC 2616 and exhaustively documented there; "discoverable", in the sense that knowing some endpoint represents a REST resource API instantly tells you quite a lot about how you can interact with it, and you can find out the rest from the responses you get when you make API requests -- which responses RFC 2616 also explains how to interpret. Not everything is simple. REST resources are, and they need not have a complex API. Poorly thought-out APIs for simple things require a lot of documentation, that mostly being lousy explanations of the interactions between an incomplete set of edge and corner cases. Well thought-out APIs for simple things barely require any documentation at all. The REST resource API is a sterling example of the latter sort; once you're familiar with RFC 2616, you can discover everything else you need from the responses you get to API requests. This is not so when redundant verbs -- POST /topics/add -- are used in a backwards namespace -- POST /add/topic -- with uncertain naming -- /add/topic, so if I want all topics do I GET /topics or /topic, or /get/topics, or what? What makes all this confusion more worthwhile than just using REST resource endpoints? Do you want people who consume your API to curse your name for making them deal with a bunch of needless impedance matching, or to effortlessly retrieve what you're offering and do something amazing with it?
  • falicon 13y ago
    I agree that the HTTP methods, when used properly, express the action...the problem is A. not everyone actually follows that properly and B. the HTTP method isn't always immediately obvious to people working with the service (i.e. newbie devs.) Having the verbs in the URI is not DRY (so that kind of sucks) but really it's not very damaging either...and so I believe the upside of (human readable) clarity outweighs the downside of a tiny bit of redundant expression. In the end, unfort. because so many don't follow RFC 2616, devs are forced to read/pay attention to the documentation for a given service anyway (at least that's always been my experience)...so in a perfect world, I would agree verbs are the methods (and not needed in the URI)...but we are a ways off from a perfect world still...
    • aaronem 13y ago
      To answer your points in reverse order: It is entirely reasonable to expect newbies to read the relevant documentation; if someone can't be bothered to read and understand one relatively succinct RFC, then any difficulty he experiences in consuming my API leaves me entirely unmoved. As hurdles go, that one's so low it's practically buried; if he can't be bothered not to stub his toe on it, how's he going to handle himself when he gets to something that requires actual effort? Someone else doing it wrong doesn't excuse you doing it wrong as well. How do you expect anything to get better if you won't turn your own hand to making it better? Sooner or later, someone will use your implementation as an example for her own. It is therefore very much worth your while to ensure that the example you provide is one of how to do it right.
      • falicon 13y ago
        I think it depends on your intent behind the API. Are you trying to create something that makes the developer/user/world easier and better or are you trying to keep your system perfect, clean, and done the right way? If it's about opening up to the larger world so that more things can be built and accomplished, you want to make it as easy as possible to use and understand across the board. You can be as strict and stern about RFC specks and rules as you want when building your thing...however, the more rigid you are, they more you'll need to be operating from a position of power from the start or the more you'll struggle to get real adoption (and to be realistic, most of us are not really releasing things from a position of power)