REST API Design Rulebook
Designing Consistent RESTful Web Service Interfaces
Publisher: O'Reilly Media
Final Release Date: October 2011
Pages: 116

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 URIs
  • Apply design principles to HTTP’s request methods and response status codes
  • Work with guidelines for conveying metadata through HTTP headers and media types
  • Get design tips to address the needs of client programs, including the special needs of browser-based JavaScript clients
  • Understand why REST APIs should be designed and configured, not coded
Table of Contents
Product Details
About the Author
Recommended for You
Customer Reviews

REVIEW SNAPSHOT®

by PowerReviews
oreillyREST API Design Rulebook
 
3.4

(based on 7 reviews)

Ratings Distribution

  • 5 Stars

     

    (2)

  • 4 Stars

     

    (2)

  • 3 Stars

     

    (1)

  • 2 Stars

     

    (1)

  • 1 Stars

     

    (1)

57%

of respondents would recommend this to a friend.

Pros

  • Concise (5)
  • Easy to understand (5)
  • Helpful examples (3)
  • Well-written (3)

Cons

    Best Uses

    • Intermediate (5)
    • Expert (3)
    • Novice (3)
    • Student (3)
      • Reviewer Profile:
      • Developer (6), Designer (3)

    Reviewed by 7 customers

    Sort by

    Displaying reviews 1-7

    Back to top

    (3 of 4 customers found this review helpful)

     
    1.0

    Do NOT buy this book

    By juanpavergara

    from Medellin, Colombia

    About Me Designer, Developer

    Pros

    • Concise

    Cons

    • Too many errors

    Best Uses

      Comments about oreilly REST API Design Rulebook:

      I needed to know if this book contained different (from that which can be found doing some basic googling) or special (expert) information about REST APIs design for a brand new project for the company I work for.

      The format of the book is good and it is easy to read. You can finish it in one single morning with 4 cups of coffee.

      The information about REST architectural style is concise and punctual. It is clear this is not the goal of the book. If you want to understand REST go read the Fielding PhD dissertation. That's the only way to go. Then REST IN PRACTICE by Webber et al.

      The information in this book IS NOT GOOD specially in regard with the classification of the resources (the Controller resources is a confusing and erroneuous concept that sadly compiles and executes and do the job). In addition, the tips for using POST method for executing this Controllers is not a good practice.

      Finally, the book is from 2011 and still the 402 error code is exposed as a Forbidden error code. I think it's 403

       
      5.0

      Design your REST API correctly

      By Dave

      from Houston, TX

      About Me Developer

      Verified Reviewer

      Pros

      • Accurate
      • Concise
      • Easy to understand
      • Helpful examples
      • Well-written

      Cons

        Best Uses

        • Expert
        • Intermediate
        • Novice
        • Student

        Comments about oreilly REST API Design Rulebook:

        As mentioned by another review, REST is a convention, not a standardized protocol. You can design all kinds of crazy APIs with HTTP, things that are not RESTful at all, and not very clean or consistent.

        I've created web services without this book, and I've created web services that were informed by this book. I wish I'd read the book before I designed my first, because the web service APIs I created guided by the Rest API Design Rulebook are significantly better -- cleaner, more consistent, better use of HTTP methods and statuses, etc.

        I especially had problems understanding when to use PUT and when to use POST; the 'rulebook' approach of the text made that distinction clear.

        As mentioned by other reviewers, the bit at the end of the book about WRML can be ignored. Maybe someday the penny will drop and I'll see the need for WRML, but right now I just want to make RESTful APIs that behave the way the REST conventions expect. I think there is such value in the bulk of the book that I'm not taking any stars off for the WRML diversion.

        I would not want to design another RESTful API without this book by my side.

         
        5.0

        Thinking About REST API-Start Here

        By Silver Wolf

        from Memphis, TN

        About Me Designer, Developer

        Pros

        • Accurate
        • Concise
        • Easy to understand
        • Helpful examples
        • Well-written

        Cons

          Best Uses

          • Expert
          • Intermediate
          • Student

          Comments about oreilly REST API Design Rulebook:

          REST is not a standard so if you are considering building RESTful applications you need to follow a consistent design schema. This book is a great start and if you follow the basic design rules you will have a better chance your applications can be used by other developers and product implementations.

          (1 of 1 customers found this review helpful)

           
          2.0

          distracting wrml pitch

          By Adrian

          from San Francisco, CA

          About Me Designer, Developer, Maker

          Verified Reviewer

          Pros

          • Short

          Cons

          • Pitchy

          Best Uses

          • Intermediate

          Comments about oreilly REST API Design Rulebook:

          The stars present in this review are here for a couple reasons. Firstly, it does what it says, which is lays out rules. Secondly, the book reasonably covers an array of http-related aspects that beginners will not likely have thought of.

          The main reason for less stars is that content is hard to reach and sometimes shakey. It is buried inside wrml pitches, and tables of things that are easy to find on wikipedia. In other words, there's a lot of cruft. While there are a lot of generic footnotes, most rules are not grounded with practical examples, or character witnesses. Particularly after encountering impractical ideas like using OPTIONS to get metadata on a resource and absolute index for pagination, I scratch my head. The author notes he didn't attempt to get consensus, perhaps to a fault in my view.

          On the whole, I can totally see the desire for readers to have rules, and there are a decent amount of good rules in this book. However, this book has a troubling chicken/egg situation: In order to cherry-pick, the reader has to already be versed enough to call BS on the unsound advice or wrml. That said, more experienced folks can cherry-pick and benefit reading this, so I've given 2 stars vs 1.

          (1 of 1 customers found this review helpful)

           
          3.0

          REST + WRML

          By Rob

          from Brisbane, Australia

          About Me Developer

          Verified Reviewer

          Pros

          • Concise
          • Easy to understand

          Cons

          • Non-standard Tools

          Best Uses

            Comments about oreilly REST API Design Rulebook:

            I've been building web based APIs of various forms for a number of years now, interacting with SOAP and RESTful services, and building some myself. It was with some interest that I picked up the book REST API Design Rulebook, getting it from the O'Reilly blogger review program.

            The book provides a decent set of information around REST, and had me either nodding my head or thinking at various stages. Its description and thoughts around REST were pretty good, but there is one area to be wary of. The book seems to do two things.

            Describe ways of doing REST well.
            Sell WRML, the authors own framework to help model REST
            I found the first helpful and useful, but wasn't as excited aboutthe second. While I understand the authors passion and desire to share what they've created, it ends up detracting significantly from the book, to the extent where I'd downgrade it from a must read to something that I'd hesitate to recommend.

            The problem boils down to this. There are a number of challenges and interesting things to solve with REST APIs. The author has created a framework to help deal with these. Naturally then the author recommends using their framework to solve the problems. Which mean the book becomes Rest API design Rulebook with WRML. I'm not convinced that WRML is the answer, so I'd hesitate to recommend this book.

            [This book was reviewed as a part of the O'Reilly Blogger Review Program]

             
            4.0

            An Attempt to Unify the REST APIs

            By Eder Andres Avila Niño

            from Paipa, Colombia

            About Me Developer

            Verified Reviewer

            Pros

            • Concise
            • Easy to understand

            Cons

              Best Uses

              • Intermediate
              • Novice
              • Student

              Comments about oreilly REST API Design Rulebook:

              This a good book for beginners willing to understand what a REST API is about, its characteristics, HTTP methods and media resources in a short, concise, panoramic way. This book is an attempt to collect the best practices to expose the external behavior that a client, web or mobile, expects from a REST API server for processing requests and returning responses. For beginners, it offers a foundational knowledge about what a REST API should provide; and for experienced developers it offers an implicit 'audit' checklist to evaluate if their APIs are REST compliant.

              For those software and web developers that want to enter to the REST API development, 'REST API Design Rulebook' is a good starting point since it explains through five sets of rules the underlying knowledge of a REST API, their structures, methods, documentation and suggested exposure to client applications and other APIs. On my opinion, and keeping proportions, this book, as a design pattern does, gives to developers the common vocabulary to discuss, specify, design, develop and test RESTful APIs.

              The book's chapters are easy, quick reading, except chapter 5 'Representation Design' which is the one that requires more intellectual effort because it explains how to structure well-formed formats for message body (i.e. JSON), hypermedia (i.e. links), media schemas and API errors. Be careful with this chapter since it introduces a new Internet format not yet approved (the WRML), but on author's opinion this new format will become the client–server more verbose with respect to the format of a returned document (i.e. resource).

              However, experienced REST developers may already know and have implemented many of the rules defined in the book, and instead be more interested in how to design the back-end service layers that conform to a RESTful API avoiding RPC or RMI practices, if possible. Such inner workings are not covered, but I think they could benefit from this book by performing a 'REST API compliant test' by taking this rulebook as a checklist.

              By taking that implicit checklist approach, this book also has the side effect of providing several criteria to evaluate if a software framework that claims to help to the development of REST APIs indeed offers a full set of features that compliant with REST behavior, much more than routing HTTP requests and isolating from user interface artifacts.

              Finally, in chapter 7 'Final Thoughts' the author depicts the need to unify a methodology to design a REST API that decreases disparities between APIs and improves team communication. Author depicts his solution known as the WRLM, akin to, say UML and RUP. On my opinion, a more detailed example included in this chapter would have been useful to show us the WRML's full potential rather than visiting the official web page.

              In conclusion, 'REST API Design Rulebook' is a good starting point to understand how a REST API is composed, to acquire the proper vocabulary and to apply a more planned API design process. As a side effect, this rulebook helps to evaluate the RESTfulness of an existing API or developer framework.

              Note: This review is in exchange for the O'Reilly Bloggers Review Program (http://oreilly.com/bloggers).

               
              4.0

              Nice book, easy to understand

              By Philip

              from HK

              About Me Sys Admin

              Verified Reviewer

              Pros

              • Easy to understand
              • Helpful examples
              • Well-written

              Cons

                Best Uses

                • Expert
                • Intermediate
                • Novice

                Comments about oreilly REST API Design Rulebook:

                I am not a web application developer so this book is not really a reference book to me. The reason why I read this book is because the use of REST API is getting ubiquitous, no matter it is on web application areas or even system administration areas. So, I would like to check out what REST API is and more importantly, its best practise. This book does give me a lot of insight into REST API and it is so well-written and easy to understand for REST newbie like me.

                The books contain 7 chapters, approximately 90 pages something, which is not a heavy book. I read it during commute and eventually it took me like 3 or 4 days to finish. For the meat of the book, I will say they are on chapter 2 to 6 which is totally 5 chapters there. They covers lots of things that would easily be ignored like the best practice to design URL of API, how does the interaction between REST and HTTP, how can one handle the resources reprenstation in a better way .... etc. All these are pretty insightful but easily ignored. Apart from these, I do really love the arrangement of the paragraph and reference materials, they are well organized and easily accessible. Overall this book is really good for those who have some computing background and really want to know more about REST API.

                Displaying reviews 1-7

                Back to top

                 
                Buy 2 Get 1 Free Free Shipping Guarantee
                Buying Options
                Immediate Access - Go Digital what's this?
                Ebook: $16.99
                Formats:  ePub, Mobi, PDF
                Print & Ebook: $21.99
                Print: $19.99