Design your API for adoption with ‘true REST’
"The only reason you'd have only a SOAP API is because you hate 80% of your addressable market." - @sramji
There's usually little argument that a REST API is easier to use than a SOAP API.
But how important is it to be 'truly' or 'strictly' RESTful? That is, adhering to standard HTTP operations or 'verbs' - GET, PUT, DELETE, POST - on well defined resources, as opposed to the common practice of embedding 'verbs' or operations as methods in a GET URL.
Typically, security is cited as the big advantage of 'true REST' (with some good discussions here and here).
However, a truly RESTful API may help you boost developer adoption. For example, imagine a 'shopping cart' API:
| Operation | Operation | URL |
|---|---|---|
| Insert new item into the cart | POST | http://api.shopping.com/InsertNewItem |
| Delete item from the cart | POST | http://api.shopping.com/DeleteItem |
| List everything in the cart | GET | http://api.shopping.com/ListCart?cartId=X |
| Get an item in the cart | GET | http://api.shopping.com/ShowItem?cartId=X&itemId=Y |
| Delete the whole cart | POST | http://api.shopping.com/DeleteCart |
While the above API isn't 'truly RESTful', it's not that hard to use. But you do have to learn the individual operations and this can get cumbersome if there are a lot of them or as the API evolves.
Instead, this 'true REST API' may be easier to learn and predict as you use more features.
| Operation | Operation | URL |
|---|---|---|
| Insert new item into the cart | POST * |
http://api.shopping.com/carts/X.xml |
| Delete item from the cart | DELETE | http://api.shopping.com/carts/X/item/Y.xml |
| List everything in the cart | GET | http://api.shopping.com/carts/X.xml |
| Get an item in the cart | GET | http://api.shopping.com/carts/X/item/Y.xml |
| Delete the whole cart | DELETE | http://api.shopping.com/carts/ |
What if we want to list all the shopping carts in the system at any one time? We would add that via an HTTP GET to:
http://api.shopping.com/carts.xml
Query parameters can still serve a purpose - making it possible to specify additional options. For instance, imagine a very large shopping cart, and you want to "paginate" the results. To look at items 20-29, you might use a URL like:
http://api.shopping.com/carts/X.xml?start=20&;count=10
Bonus: True REST makes analytics easier
It's a lot easier to build reports that segregate and analyze traffic by URL than to build logic that tries to do this by methods or combination of methods. Good API analytics helps you optimize features, debug problems, and weed out traffic that can slow down your service.
What if your 'non-strict' REST API is already out there?
It might not be that big a deal if your API is very simple or 'read-only' API with information that isn't too sensitive (such as a free search API). Or you can map a non-RESTful API into a 'truly RESTful" API with custom code or API management tools thatperform API transformations.
* A note on POST VS. PUT
* One way to insert an item in the shopping cart is to use POST to update the shopping cart by sending it a new item. In this case, we are using POST to send the server an instruction that essentially tells it to insert some new content to the existing resource. This is why we use POST -- it is like an "update" in a database.
Alternately, we could add the item by using PUT to a new URL, such as:
PUT http://api.shopping.com/carts/X/items/Y.xml
But if we do this, then we need to somehow give our item some sort of unique URL by picking a value for "Y". This is kind of a strange thing to do, so it may be more natural to use POST and have the response include the URL for the new item, so that we may retrieve it later using GET or delete it using DELETE. Still, sometimes using PUT like this makes sense.
This all comes down to the difference between PUT and POST in the HTTP spec. POST modifies something that already exists, and how that thing is modified is up to the server. PUT replaces the entire contents of the URL with new data. Plus, like GET, HEAD, and DELETE, PUT is idempotent, which means that if you call it more than once, it has the same result every time, whereas POST may keep doing what you ask it to do over and over again
COMMENTS (6) | Add a comment
March 10, 2010 at 11:19 am Alan Wilensky
Ok, I am no defender of SOAP and WDSL. AS a matter of fact when the standards came out, my reaction was, “yeah right, that’s gonna work”.
However with that said: REST vs. SOAP religion is just a new Mac vs. PC thing. There are easy and usable SOAP APIs, and there are HORRIBLE REST APIs.
In the case of a network command grammar, such our very own ECGridOS service delivery platform for EDI communications, our WSDL unpacks nicely in every IDE, and we use a very simple command and return grammar. So, with one accesible endpoint, we pack a lot of easy to use network goodness into our SOAPyness. Even inexperienced Visual Studio apprentices master the ECGridOS network grammar fairly rapidly.
If our EDI API was a RESTful implementation (in the works with a reduced call footprint), there would be a greater number of URIs. The current WSDL is at 90+ functions, of which 35ish or less are used by almost every application.
So, in summary, I think that the leading quote of this post is just…..baloney, particularly in this era of better IDE’s. If it were 4 years, ago I might agree. One might say that REST was a response to lousy tools support for WSDL. This is no longer true, and properly defined SOAP functions today seem like local code. Make it as bad or as elegant as you wish, just like half the REST mess out there.
March 10, 2010 at 1:27 pm Greg Brail
Important points, Alan. When people get me talking about this topic, I usually say (as we do in our whitepaper) that you have to know your audience. If your audience is fluent in Visual Studio or Eclipse or various other tools that are good with SOAP and WSDL, which seems to be the case for your customers, then they’re fine.
However, there are an awful lot of people out there who either don’t have ready access to good SOAP tools (for instance, they’re iPhone or Android developers) or they hear the words WSDL and they start to tune you out… Sam’s deliberately provocative comment was meant to remind us that there are an awful lot of developers out there who, unlike you and me, find SOAP to be a barrier to entry.
Not sure what you meant about the URLs, BTW—a REST API does use a lot of URLs, but there are some nice server-side frameworks today that make it easier to deal with all that.
March 10, 2010 at 3:11 pm Alan Wilensky
Should not every REST class have a unique URI?
Even so, I thought that sticking with SOAP would lose the Ruby and PHP enterprise crowd,but it turns out that even folks have decent environments to consume that WSDL, unwrap it, and make the calls available.
But we are creating a subset REST API with probably 1/3 of the SOAP calls in post get form. because theere are folks who want it. Good enough for me.
But I still think the dichotomy is more religious than real,
March 31, 2010 at 4:24 am Taner Ozdas
Good post about the design of REST API, but there is one important missing part is REST API security. Please could you mention about the security solution possibilites like basic authentiaction , ssl or oAuth . Thank you
April 23, 2010 at 7:29 am psgels
I think you missed something about ‘true’ REST. Your definition above misses the hypermedia-part: using links to navigate through your resources. If you just list a bunch of links you’re simply doing some form of RPC.
Go and read the Richardson Maturity Model for more information:
http://martinfowler.com/articles/richardsonMaturityModel.html
April 28, 2010 at 4:11 pm Greg Brail
You’re right—there are lots of ways to be more and more “RESTful” and there are people and books and conferences who write about it. I was just trying to get across the idea that more basic REST concepts, like using well-structured URLs as well as using HTTP verbs, can make an API easier to use and faster to learn.
I get the model of “hypermedia controls,” although I have to say it’s not something I’ve encountered before in real APIs. The advantage is that API replies are more self-describing, and the server can change the URL structure without worrying if the clients know it. The disadvantage is that it relies heavily on clients to do the right thing (which they don’t always do). It also introduces interesting security concepts that the client has to think about—namely, that the server is going to return a brand-new URL path and expect that the client will go there. That means that a good client must not only pay attention to that URL, but make sure that it isn’t actually redirecting to some malicious host. That doesn’t make it a bad model but one that I think is going to take some thinking to implement properly on both sides.
*required ADD A COMMENT