Two months ago we had the pleasure to interview Mike Stowe, a Developer Relations Manager at MuleSoft who has recently published a book on API Design. Today, we are going to review Undisturbed REST: A Guide to Designing the Perfect API to let you go a little bit deeper into what it holds for you.
The first thing you will notice is the book cover, cozy enough to make you want to sit back just as the guy in front of the laptop does. Right there you will see sticker-like one-sentence feedback by Arnauld Lauret (API Handyman), a devoted API believer saying “I wish I had read this kind of book before starting my first API project.”
The book was intended to teach you how to design a long-lived API that would meet your business objectives and be a marvel to work with for your users. There is everything you need to know to build a flexible API that you and your users will love.
Undisturbed REST: A Guide to Designing the Perfect API is well-structured and comprises 13 chapters, the last of which is dedicated to some final thoughts of the author. There are also two appendixes you will probably find helpful, one sharing informative & amusing API resources and a checklist to make sure your API is ready for developers.
Let us get deeper into what theoretical basics are laid out in the book.
The title of the first chapter, What is an API, speaks for itself. The 13 pages give the essentials of different types of APIs with special prominence given to REST and some principles that will cost effort at first but will turn rewarding in the long run.
Planning Your API provides ten points to consider before rushing to work with the code. Some of them are presented in the form of questions so that you can ask yourself whether this or that moment was taken into account. Of course, each important statement is followed by the author’s word.
Designing the Spec clarifies the pros of having a plan of what your API is going to look structurally. In this chapter, Mike Stowe suggests using a process called Spec-Driven Development that will add some weeks to the API lifecycle but will help to make your API long-lasting and flexible in return. Here he also provides a review of the three specs, Swagger, API Blueprint, and RAML, to which the next chapter, Using RAML, is dedicated.
Chapter 5 tells about Prototyping and Agile Design. It will teach you how to mock your API and involve developers to give their word about it so that you do not miss a thing before the actual release.
In the next chapter, you will find information about Authorization and Authentication. Here Mike Stowe explains what their role is as well as dwells on generating tokens, types of OAuth, and the easiness of adding OAuth to RAML.
Chapters 7 will help you while Designing Your Resources. The 18 pages contain some words on decoupled architecture and the use of nouns as well as details on content types. Versioning and caching are also included in the chapter.
The next part of the book is dedicated to Designing Your Methods. There you will find CRUD, the difference between an item and a collection, and HTTP methods explained.
Handling Responses provides some knowledge on various errors and status codes that is preceded by the reasoning of the importance of making sure that clients and consumers are able to quickly implement your API and understand what is happening.
In the chapter Adding Hypermedia, the author outlines hypertext and HATEOAS, speaks about hypermedia implementing and common hypermedia specs such as Collection+JSON, JSON API, HAL, JSON-LD, CPHL (created by Mike Stowe in 2014), and Siren. He also mentions other specs and some hypermedia challenges.
Managing with a Proxy describes what is to be done after your API is designed and built, that is, protecting and scaling it. API management components such as API access, throttling, SLA tiers, analytics, security are also overviewed here.
The last chapter before the author's final thought is Documenting and Sharing Your API. It teaches how to write good documentation, overviews some documenting tools, and emphasizes the role of support communities as well as SDKs and client libraries.
We believe that Undisturbed REST: A Guide to Designing the Perfect API is worth reading, especially if you are new to the world of APIs. The material that you might expect to be difficult to comprehend is arranged and explained in such a way that you will have no difficulty absorbing the knowledge. And, of course, the style and friendly tone. The vibes are just as positive as those in the interview mentioned above.
If you are looking for a book to get into the basics of APIs, their design, management, and documenting, be sure to choose Undisturbed REST: A Guide to Designing the Perfect API as your manual. Fortunately, the book is available on the Mulesoft website, so all you need to do to start reading and loving it is to download it here.
The review is brought to you by API2Cart team.
API2Cart is a unified shopping cart data interface that will help you access the database of 40+ eCommerce platforms. Feel free to schedule a FREE call to find out more.
