REST API Design Rulebook

by Mark Masse

In todayâ??s market, where rival web services compete for attention, a well-designed REST API is a must-have feature. This concise book presents a set of API design rules, drawn primarily from best practices that stick close to the Webâ??s REST architectural style. Along with rules for URI design and HTTP use, youâ??ll learn guidelines for media types and representational forms. REST APIs are ubiquitous, but few of them follow a consistent design methodology. Using these simple rules, you will design web service APIs that adhere to recognized web standards. To assist you, author Mark Massé introduces the Web Resource Modeling Language (WRML), a conceptual framework he created for the design and implementation of REST APIs.

Genres: Programming, Technology, Computer Science, Software, Technical, Nonfiction, Web

136 pages, Paperback

First published January 1, 2011

Reviews

[Rob · Rating 2 out of 5]

If you're new to the world of REST APIs, and if you're looking for a good set of working rules on how to design them, then Mark Massé's REST API Design Rulebook should live up to its title just fine. It's a short book (you could read it in an afternoon) and it tackles the subject matter in a direct and orderly fashion. It starts with a brief history lesson, quickly reviewing the history of the world wide web, of HTTP, and of the emergence of the whole notion of "RESTful" APIs and services. From there, he lays out the six constraints of the web's architectural style, [1] and how RESTful designs fit into that. The rest of the book is basically just a series of "rules" to follow when designing a REST API, along with use-cases, examples, and justifications for each of those rules. Many of these rules seem very common sense and sound a lot like every other bit of advice you've ever received about (for example) naming variables and methods; [2] other rules seem sensible but get boxed in by "real-world" difficulties [3] or else seem counter to the prevailing wisdom; [4] still others seem to be little more than evangelizing for Massé's own proposed WRML design/modeling framework.

For me, the highlight reel included: the first three chapters (on identifier design, interaction design, and metadata design), and some of the discussion in the final chapter ("Client Concerns") about security, and the overview (however brief) of JSONP and CORS as solutions for some otherwise challenging situations.

The two bits where it went off the rails a bit for me: (1) Any of the discussion of "hypermedia" and/or between-document linking--I haven't encountered this much (at all?) in the real-world and a lot of it seemed overkill to me, to go into that depth on how to link documents from within the API. [5] (2) WRML: what? Even after reading the whole book, I was still left wondering what exactly WRML was intended for, and what it would buy me as a developer. It seems that Massé wrote this book in part to evangelize this framework, but I could not quite get my mind sufficiently around it to say that I got it.

On the other hand, Massé does a great job with the "rules" (again: especially in the first half of the book) and I would recommend this to anyone that needs an introduction to REST API design. That being said, after absorbing this one, you'll probably want to explore further with one of the other O'Reilly books on the subject, and/or find yourself a couple of resources on OAuth.

(Disclosure: I received an electronic copy of this book from the publisher in exchange for writing this review.)

----

[1] (1) Client-server; (2) uniform interface; (3) layered system; (4) cache; (5) stateless; and (6) code-on-demand.

[2] E.g., use singular nouns for documents; use plural nouns for collections and stores; use verbs ("and verb phrases") for actions, etc.

[3] In Chapter 2 ("Interaction Design with HTTP") Massé advises you to use the pedantically correct HTTP methods for performing the corresponding actions: e.g., if you want to delete a document, send a DELETE request to the document's URI. However, as most web developers already know, mainstream browsers will not respect any HTTP methods other than GET or POST--so you can forget trying to use PUT or DELETE as a form's method, and you're stuck using POST as a wrapper. (Here is a good Stack Overflow thread on the subject.)

[4] E.g., all those API URIs that have a '/v1/' in there somewhere? to specify the API version? Massé says: "Don't do that."

[5] And as an aside, it was very unclear to me how the rel (relationship) attributes were even suposed to be defined. Some central standard? Part of WRML? Do you make stuff up and furnish an end-point in your RESTful API to explain the rels?

[Vladimir · Rating 3 out of 5]

All WRML parts are useless. It would be much better if author didn't include them into the final version. It seems to be the weak attempt to make his framework popular. Nice try, but no...
Apart from this, the book is quite good.

[Christoffer Klang]

I skipped the WRML parts, but otherwise lots of good points.

[فاروق الفرشيشي · Rating 2 out of 5]

The book was perfect until it changed to a boring promotional catalogue for WRML thing that nobody uses. I may say that the book is predicated now. That's a pity because HTTP notions and basic REST principles were delightful.

[Ahmad Hajjar · Rating 4 out of 5]

Until the day before reading this book, I had this misunderstanding about RESTful API/Services, a lot of services out there, claiming to be RESTful are just claiming so because they use HTTP as the communication media, while this is only the beginning, to be RESTful the application has to comply with HATEOAS, using Hypermedia As The Engine of Application State is the thing that makes a RESTful app, a RESTful app.

However, the author is exaggerating in using and/or emphasising on the use of links and relations in the book's examples, I see this as a good thing to showcase how a RESTful representation should be, but IMHO I see this as overkill. But if we take it from another angle, standardising could always be the answer to a lot of this industry's problems. Here in this case, standardisation can help the client's program (if they follow the REST Standard) to use the application and navigate through it, and any of its versions, by just knowing the rootdoc. In this case, the client's app will use the API just like any human who visiting a Website and "navigating" using hyperlinks, and any changes in the server side (resources location, objects representations, or behaviours) will not affect the clients, in this perfect world the server developers and client developers will be totally independent :) they don't even share "API documentation" because in this case the API is describing itself.

[Michael · Rating 2 out of 5]

This is a better book than my pure star rating would seem to indicate. It's not that I didn't like the book - it was OK.

However, as a highly opinionated book, I wonder how widely accepted the ideas being laid down as rules actually are. I think there is much here that people can agree is best practice when designing a RESTful API. However, I'm left with the feeling that much of the rest of it is a one-man campaign towards standards that may never be adopted at large.

So, reader beware: I suspect these "rules" are pretty solid for the author, but I don't know how widely accepted they are in the industry at large quite yet.

[Neville Ridley-smith · Rating 4 out of 5]

Good as a reference. Weird if you read the whole thing.

A large chunk of the book - most of the second half - is about this thing called WRML. It's pretty useless as far as I can tell. It reminds me of other attempts to make things 'discoverable', like Jini or Soap directories. The fact of the matter is, you generally *never* want to dynamically interrogate a web api. You just want to use one to get something done. WRML may slightly help with this but not really - documentation and examples are always going to be better.

Anyway, the first half of the book is still really good in helping clarify best practices for REST API designs. Dip in and out as needed.

[Robert · Rating 2 out of 5]

Two huge problems with this book. It's short and very repetitive so the information content is about a couple of blog posts. The 'rules' are highly subjective, and much of the book is pushing the author's WRML 'standard' which I've never seen in the wild. The only real positive is that it's a comprehensive survey of the issues you need to think about when designing a REST API: just don't take the rules as gospel and research best practice from major APIs so you understand the context.

[Cody Ray · Rating 3 out of 5]

This provides a good basic list of rules to follow for REST APIs, intentionally opinionated and setup following the must/should/may terminology. About half of the book reflects current REST practice, and the other half advocates for a new proposed standard the author created called WRML to build hypermedia-powered APIs.

I think this book tried to do too much, both documenting current real-world practices (API specifications) and hypothetical future world practices (hypermedia). The first part was a good overview of current REST design though it could've covered more areas in more depth if it hadn't tried to also tackle hypermedia. And the hypermedia portion of this text is better addressed by RESTful Web APIs [1] and RESTful Web Clients [2], so I'm not sure how much more this adds.

[1] https://www.goodreads.com/book/show/1...
[2] https://www.goodreads.com/book/show/3...

[Matthew Horvat · Rating 3 out of 5]

I've seen other reviews comment that this book is great if used as a reference, but strange if you read it straight through, as I did. Since it is a rather short book, I ponied up to the so called bar and went for it.

There are definite things to think about when design a REST API, but most cases the user will be using a framework such as Express of ASP.NET which will do a lot of the heavy lifting for you.

I'll keep a link to the ebook handy in case I have questions going forward, as a reference is the best way to use this book, not necessarily as a set of rules that must be followed explicitly.

[Lucille Nguyen · Rating 3 out of 5]

The good: talks about the history of the Web, the Genesis of REST, and details design principles for making RESTful Application Programming Interfaces.

The meh: gets a bit into the weeds sometimes. Could have been more of a rulebook than a dictionary with a better editor.

The bad: bro we get it you wanna shill for WRML but with historical retrospect your preferred modeling language is dead maybe just provide the rules.

[Christoph Kappel · Rating 3 out of 5]

Actually this book was a kind of disappointment. There are so many aspects about REST design that should be covered, but maybe it was my own problem with expectations?

It mostly covers some pretty basics and endless pages about the author's approach to define specs with something called "wrml". I must admin I've never heared about this before.

[Jakub Šimek · Rating 2 out of 5]

A quick and somewhat interesting read. Half of the book contains good guidelines to follow when designing REST APIs, the other half is an ad for author's WRML format that didn't end up getting much traction (which makes the read quicker and less interesting).

[Егор Лебедев · Rating 4 out of 5]

Good ideas to design rest api, readed in two evenings. Author use his framework for api desugn so that part of book where he explains his framework not neccesary to read.

[Olu · Rating 4 out of 5]

As the name indicates, it is simply a RULE Book and so, it is not as detailed as a first timer still being introduced to REST would expect.

[Vaibhav Kulkarni · Rating 2 out of 5]

First three chapters were good

[ROUCAUTE · Rating 4 out of 5]

Quite heavy but valuable reading. Could be structured well.

[Emma · Rating 3 out of 5]

Some good advice, but a bit outdated.

[Chifeng Chou · Rating 4 out of 5]

Very useful. I skipped WRML part because it's not relevant to me.

[Filip Cvetko · Rating 4 out of 5]

Too boring to read in its entirety, but probably a very good reference.

[هدى · Rating 3 out of 5]

It was a good book at the beginning then I got bored in the part of Media URL schema.
But I get nice knowledge from reading it.

[Harry · Rating 4 out of 5]

Definitely solid, however not as in-depth as I would like in order to feel confident in designing APIs

[Kviro Gabunia · Rating 2 out of 5]

ვნახოთ ტესტინგის შუალედურში რა ქულა მექნება და მერე მოვუმატებ თუ რამეა რეიტინგს დდ

[Ahmed Ouda · Rating 3 out of 5]

A brief rulebook for REST APIs. It is a little outdated and shallow, but nice intro for those who haven't designed REST APIs before.

[Reese · Rating 5 out of 5]

This book probably should have been titled 'Hypermedia REST API Design Rulebook', to prevent complaints from people who don't understand the real meaning of REST, but I don't know if that terminology even existed when this was published. At the very least, it should have more clearly separated the book into sections, stating the intended audiences explicitly. There is plenty that can be helpful to people writing a 'REST' API, and then there is a bunch of stuff that is useful to people trying to design a true hypermedia REST API, and finally, there is a fair amount that could be useful to someone writing a generic media type specification (but most normal people wouldn't care to read). Most of the complaints I've seen are based on the subjects meant for the 2nd and 3rd audiences. Complaints about the inclusion of WRML media type details may be well founded, but the ideas behind this media type should definitely not be dismissed. As far as examples of good APIs, Twilio's API uses a media type that follows some of the principles behind WRML, and Github's uses a bunch as well.

Before this book, I was struggling to comprehend how to fulfill all the requirements of a true REST API. Including schema as a parameter in the media type filled the gap for me. I was also able to include many of the insights about using HTTP properly, like conditional PUT requests using headers, avoiding concurrency problems.

[Greenicicle · Rating 1 out of 5]

The book tries to establish a set of rules for REST interfaces - I'm OK with that, it's what its title says. When you define rules, you take an opinion, that's fine. And most of what is defined as a rule is something I'd support as a good practice. A possible benefit of this rule book would be to provide some compact, memorizable, and clear guidance on good practices.

But then there's this obsession about WRML.

WRML is a proposed way of defining the content types and schemas of REST APIs - see http://www.wrml.org/about. And what do we find as the sole literature on WRML: the REST API Design Rulebook. WRML has about zero industry acceptance; I never heard of it, and it does not even have a wikipedia page. And yet the REST API Design Rulebook puts it into the heart and center of every halfway advanced topic. Now a "rule" that is centered around an obscure standard proposal is totally void, and so this book is a simple waste of e-ink (even if that was its only fault, which it isn't).

[Kaido · Rating 3 out of 5]

First part of the book gave me superb ideas about my API design but the second part was a bit too specific. Of course I agree that these things should be considered but as the frameworks out there, they are not very easy to bend and you have to follow the documentation as well in programming. otherwise good book.

[TN · Rating 3 out of 5]

Good, but very short book.

[Vova Mihura · Rating 2 out of 5]

Somehow useful... There is a nice description about the types, controllers, methods, but I want more...
The authors concept of WMRL is too complex.

[Pedro · Rating 2 out of 5]

Nice basic rules for REST beginners, but too few useful information once you take the WRML parts out.