What do you think?
Rate this book
REST API Design Rulebook
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.
Learn design rules for addressing resources with URIsApply design principles to HTTPâ??s request methods and response status codesWork with guidelines for conveying metadata through HTTP headers and media typesGet design tips to address the needs of client programs, including the special needs of browser-based JavaScript clientsUnderstand why REST APIs should be designed and configured, not coded
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.
Learn design rules for addressing resources with URIsApply design principles to HTTPâ??s request methods and response status codesWork with guidelines for conveying metadata through HTTP headers and media typesGet design tips to address the needs of client programs, including the special needs of browser-based JavaScript clientsUnderstand why REST APIs should be designed and configured, not coded
161 pages, Kindle Edition
First published January 1, 2011
92 people are currently reading
253 people want to read
Ratings & Reviews
Friends & Following
Create a free account to discover what your friends think of this book!
Community Reviews
Displaying 1 - 30 of 32 reviews
June 13, 2012
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 and 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. ()
[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?
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 and 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. ()
[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?
April 19, 2019
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.
Apart from this, the book is quite good.
Read
June 2, 2014I skipped the WRML parts, but otherwise lots of good points.
June 11, 2019
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.
March 13, 2017
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.
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.
November 7, 2011
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.
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.
November 14, 2013
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.
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.
December 1, 2011
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.
August 11, 2019
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] /book/show/1...
[2] /book/show/3...
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] /book/show/1...
[2] /book/show/3...
July 9, 2022
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.
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.
April 26, 2021
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.
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.
September 24, 2019
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).
May 16, 2018
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.
March 9, 2019
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.
January 24, 2020
First three chapters were good
This entire review has been hidden because of spoilers.
January 26, 2020
Quite heavy but valuable reading. Could be structured well.
April 18, 2020
Some good advice, but a bit outdated.
November 11, 2021
Very useful. I skipped WRML part because it's not relevant to me.
January 2, 2022
Too boring to read in its entirety, but probably a very good reference.
January 31, 2022
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.
But I get nice knowledge from reading it.
July 7, 2023
Definitely solid, however not as in-depth as I would like in order to feel confident in designing APIs
April 7, 2025
ვნახოთ ტესტინგი� შუალედურში რა ქულა მექნებ� და მერე მოვუმატე� თუ რამე� რეიტინგს დდ
September 1, 2015
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.
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.
December 3, 2011
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 . 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).
But then there's this obsession about WRML.
WRML is a proposed way of defining the content types and schemas of REST APIs - see . 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).
December 26, 2016
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.
December 23, 2011
Good, but very short book.
September 30, 2012
Somehow useful... There is a nice description about the types, controllers, methods, but I want more...
The authors concept of WMRL is too complex.
The authors concept of WMRL is too complex.
June 5, 2024
Nice basic rules for REST beginners, but too few useful information once you take the WRML parts out.
October 23, 2013
Good stuff - designing easily discoverable, consumable and maintainable REST services - all basics covered.
March 5, 2014
Nice thoughts, but feels like an academic paper out of touch with modern dev.
Displaying 1 - 30 of 32 reviews
Can't find what you're looking for?
Get help and learn more about the design.