Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

So, a RESTful service has a fixed set of verbs in its vocabulary. A RESTful web service takes these from the HTTP methods. There are some supposed advantages to defining a fixed vocabulary, but I don't really grasp the point. Maybe someone can explain it.

Why is a fixed vocabulary as outlined by REST better than dynamically defining a vocabulary for each state? For example, object oriented programming is a popular paradigm. RPC is described to define fixed interfaces, but I don't know why people assume that RPC is limited by these contraints. We could dynamically specify the interface just as a RESTful service dynamically describes its content structure.

REST is supposed to be advantageous in that it can grow without extending the vocabulary. RESTful services grow dynamically by adding more resources. What's so wrong about extending a service by dynamically specifying a per-object vocabulary? Why don't we just use the methods that are defined on our objects as the vocabulary and have our services describe to the client what these methods are and whether or not they have side effects?

Essentially I get the feeling that the description of a server side resource structure is equivalent to the definition of a vocabulary, but we are then forced to use the limited vocabulary in which to interact with these resources.

Does a fixed vocabulary really decouple the concerns of the client from the concerns of the server? I surely have to be concerned with some configuration of the server, this is normally resource location in RESTful services. To complain at the use of a dynamic vocabulary seems unfair because we have to dynamically reason how to understand this configuration in some way anyway. A RESTful service describes the transitions you are able to make by identifying object structure through hypermedia.

I just don't understand what makes a fixed vocabulary any better than any self-describing dynamic vocabulary, which could easily work very well in an RPC-like service. Is this just a poor reasoning for the limiting vocabulary of the HTTP protocol?

Reflection

Just to clarify my thoughts a little better than I have done. Suppose you are designing any general purpose API, maybe not even web facing. Would you be happy if someone said you can only use these method names on your objects? REST isn't restricted to HTTP, but consider the situation where every API you write, web facing or otherwise simply consisted of objects containing GET POST PUT and DELETE methods. So that object.foo method you wanted to define isn't possible. You have to define a new object called foo, and call its GET method. That's essentially how REST works, and it makes me a little uncomfortable to think about it. You don't have any better generic understanding of what foo does, you were just forced to create a new object for what is essentially a method on a parent object. Furthermore your API is no less complex, you have just hidden interface complexity by creating more objects. RESTful web services force us to adopt an interface which may or may not be sufficient in the context of the API we are exposing. Perhaps there is a good reason for doing this with web facing APIs, but a good reason to not adopt standard interfaces for every object in every general purpose API. A practical example would be appreciated.

share|improve this question
    
To help users quickly parse your question and answers, you might consider adding your "Updates" as separate answers (particularly the "Another Update" section). This is encouraged: blog.stackoverflow.com/2011/07/… –  Johann Aug 22 '13 at 23:39
    
@Johann thanks, the further updates now exists as the accepted answer for this question. –  Matt Esch Aug 22 '13 at 23:53
add comment

6 Answers

The "verb" and "noun" terminology is somewhat unfortunate here. As you already mentioned, you can easily create object for function. All object oriented languages except Java have that transformation built-in and in Java you end up doing it all the time anyway ending up with lots of objects with single method and often one called "invoke", "execute", "apply" or somesuch (so it's the programming languages where the "verb"/"noun" distinction actually doesn't make sense).

The "verbs" of REST is more like classifying your methods to getters, setters (deleters; can be considered kind of setters) and other. And trying to do everything with getters and setters. The reason for this is:

  1. Easier semantics in face of communication failure, since both getters and setters are idempotent. Getting the resource twice has no additional effect and nor does setting it to the value it already has.
  2. Defining some semantics that can be used by possibly caching proxy that does not understand the specific interface. Getters are cached and setters are known to invalidate the cache.

HTTP was designed from the beginning with both caches and fault-tolerance in mind, so these two points lead to it's four basic methods:

  • GET is a getter. It's assumed not to modify server state and return the same value each time with possibility to specify expiration and revalidation policy.
  • PUT and DELETE are the setter and deleter (= setter with nil). They are not normally used in context of normal web, but make sense for REST.
  • POST is a generic "invoke" kitchen sink for which caches can assume nothing.

REST is a design pattern describing how to use raw HTTP or similar network protocols to implement interface that allows easy handling of failures by simple retrying and works nicely with caching proxies.

It doesn't correspond easily to regular object-oriented programming API. I think it is actually a good thing. The challenges of interfacing over network, which is inherently unreliable and where round-trips are much slower than transferring even moderate amount of data call for different design approach than in-process API, so when it looks different, people don't try to apply invalid experience from the other domain that much (that's the bane of SOAP, XML-RPC and such; it looks like procedure calls, but doesn't work like it and ends up being pain to work with).

share|improve this answer
add comment

The essential idea is that complexity is expressed through the resource representation, and so additional verbs are not needed. As some have put it - "In REST, nouns are good, verbs are bad."

If you look at the four REST verbs, they can be mapped to the basic CRUD operations, essentially allowing you to do whatever you want with your resources. That is -

POST - Create the resource

GET - Read the resource

PUT - Update the resource

DELETE - Delete the resource

What else do you need?

share|improve this answer
    
I can facilitate a verb in a RESTful service by creating a resource for doing it. As you say, I don't need additional verbs just more resouces. I just don't see why it's any better to pretend any abstract verb is a noun when what I want to do is really a verb. It seems like verbs are forcibly constrained for no reason, and I am avoiding the problem by creating nouns that perform the required actions when accessed with a small set of verbs. Why would it be any better to do that? There has to be a good reason for it, something I can quantify as a practical example. –  Matt Esch Mar 25 '12 at 4:38
3  
Get a list of all resources, get a list of all resources with given constraints, update or delete a bunch of resources at the same time, create two different types of resources together atomically (so that both creations fail or succeed), delete all resources satifying a given condition... The list of things that one may want to do is quite long. One can fit them into a REST API, but it is not always natural. It also does not help that GET does not allow a body, so complex filtering conditions become akward. –  Andrea Jul 20 '12 at 22:28
add comment
up vote 2 down vote accepted

Consider a language where all constructs (such as functions) are objects. Then the RESTful verbs are simply calling conventions and assignment statements. For JavaScript you could define a fixed verb syntax like INVOKE for calling a function, DELETE (the same as delete in js) for deleting an object on another object, SET for assigning a value and RETURN for returning a value. We could use the HTTP verbs to mean the equivalent POST - invoke function, PUT - assign value, GET - return a value, - DELETE - delete an object. I was caught up in the idea that the HTTP methods were actually describing object methods, actual object interfaces, that I failed to see that it could actually describe much lower level concepts, such as the basic language constructs which are clearly fixed and finite in all sane languages. HTTP verbs define the object manipulation syntax and the higher level object structure defines the API methods.

And of course it's helpful for routing/proxying to have a fixed vocabulary to reflect on.

share|improve this answer
add comment
  • Because a professional programmer anticipates hundreds, if not thousands of method names otherwise. What seems pointless at a smaller small can be a very big deal as the application becomes bigger.

  • Because there's no need for standards about method names when they are already defined.

  • Because the main aim of code is be readable without such additional translations.

  • Because it encourages and aids in the identification of 'when' another class should be broken out.

  • When you take over code it's reasonable and actually possible to understand what and how it does it much quicker.

  • It provides a common vocabulary and thus level of abstraction so you can focus on other details and see patterns.

  • It makes finding bugs easier as common code and approaches be easily be checked.

  • When you're working with multiple 'layers' such as one does in web development, knowing what urls match to which action names is very handy for debugging.

Overall you don't 'always' need it, but like most standards, it makes a lot of sense to aim to try to use it!

share|improve this answer
    
Addressed in order 1) So a programmer anticipates hundreds if not thousands of resources otherwise? We already anticipate methods in the libraries we use. 2) So we need standards for method names but not for resource names? I fail to follw that logic. 3) Not sure what you mean by translations. If you tell me a resource exists I have to understand it. If I tell you a method exists you have to understand it. The only thing I really care about is which of my actions will have side effects 4) Could you expand –  Matt Esch Mar 25 '12 at 4:47
    
5) again could you expand. I am a programmer. I am used to working with well defined object structures. Why would we not use this same mechanism for defining all of our APIs if it's truly any better? 6) No level of abstraction is worth considering without justification 7) Again could you expand. If we benefit in this way surely we should code all of our APIs like this. 8) I would expect any object to expose its methods directly. /object/method can't be confused. We define the standards by choosing to adopt them. I am lacking motivation at the moment. –  Matt Esch Mar 25 '12 at 4:51
    
Matt you seem a little argumentative but I will say that for 2) I didn't say resource would not need standards 3) You will not need to understand a method such as 'update' or 'new' or create' because you know exactly what those do according to the standards. However what about 'MsgToPrimary' what does that do? Create a msg? Update a status? Send an email? 7) Yes most API's could benefit from this and many do. I would try to focus on the notion standard standards and conventions are helpful and I can see your updates are showing that. –  Michael Durrant Mar 25 '12 at 22:43
    
I am just trying hard to understand the benefits. The strong counter-arguments need to be addressed to clarify the problem. Still I understand that a fixed set of verbs is sort of a language description, but I don't really agree that it makes easier to understand. You can't take away an expressive set of verbs and say hey, we now understand all the verbs, when we don't understand all of the resources. Resources are replacing verbs. We replace the arbitrary verb foo with a resource called foo. Our understanding of foo is no more clear than it was when foo was a verb. –  Matt Esch Mar 25 '12 at 22:56
add comment

The alternative is something horrible: WSDL (aka Web Service Definition Language), which is a (clumsy) way to programmatically describe (somewhat) arbitrary APIS.

REST severely limits the verbs, pushing almost all application-specific variation into the payload of the document. The benefit of doing that is that many client implementations can communicate with many heterogeneous services. The clients and servers may be completely unknown to each other, some not being written yet.

There's a podcast in which Stefan Tilkov explains REST nicely.

share|improve this answer
add comment

Simple is good.

There are cases when you need extra verbs and complexity, but most problems can be trimmed down to simple CRUD actions on resources, and that's what REST tries to promote. When you think about most web applications, in the end they read and persist records in a data store, which use the same very simple actions.

object.foo() is all good, but what does it do? What is it returning? Is it modifying the state of object or any of its dependencies? Can you call it twice and get the same result or is it going to give you two different values? If you have object.bar() as well, do they need to be called in a specific order?

There is a lot of knowledge required in using a rich API, and they usually have their own conventions (i.e. setFoo is going to mutate the object, getBar is probably idempotent, dispose() or destroy() means no other calls on the same object will be possible, etc...)

share|improve this answer
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.