Why is a small fixed vocabulary seen as an advantage to RESTful services?

Question

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.

Answer 1

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).

Answer 2

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?

Answer 3

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.

Answer 4

• 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!

Answer 5

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.

Answer 6

Yes a rest api has a fixed set of verbs, but it doesn't have to be limited to (or include GET, POST, PUT, DELETE). I would look at the GET, POST, PUT, DELETE as a default implementation of REST that works for 80% of all the systems out there.

Other systems that are implementing more than crud operations can (and do) implement their own verbs for their REST API's. Verbs like Publish, Consume, Rate, Comment, Search, Browse can be added and implemented in a REST system. While some might say that a larger vocabulary might make it more complicated, my answer is that it depends. If your target user are tech heads who understand what a POST is then yes it could be more complicated; however, if your API's target users are real people (i.e. people who don't code and don't know what a POST is), then real verbs are much much easier to use. In fact having an appropriate set of verbs for your API helps keep the urls short (which is important if you want to have users type them in a browser. If you use a custom vocabulary, you'd want to make sure that your API and its verbs are well documented. When using a custom REST api, you'd want to ensure that your 'read only actions' as an HTTP GET and 'write actions' with POST.

The teen social network, Piczo.com, (may it rest in peace) featured an extended REST API (including the verbs mentioned above) that was implemented in 7 different languages!

Answer 7

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...)