Build APIs You Won't Hate By Phil Sturgeon
Over the weekend, I re-read "Build APIs You Won't Hate: Everyone and their dog wants an API, so you should probably learn how to build them" by Phil Sturgeon. This book provides a quick, yet fairly thorough look at the end-to-end development of APIs (Application Program Interface) including everything from planning and seed-data to serialization and side-loading to status codes and errors to authorization and security. Complete with concrete examples laying the foundation of each chapter, this book provides a truly practical guide to thinking about and implementing APIs in your own application.
| |
|
|
||
| |
 |
|
||
| |
|
|
As you might be able to tell by the subtitle of the book, Sturgeon uses a light, jovial tone when discussing API theory. I personally enjoyed his approach and I felt that his prose walked the fine line of being entertaining but, at the same time, not distracting from its own technical merits.
If you return an HTTP status code of 200 with an error code, then Chuck Norris will roundhouse your door in, destroy your computer, instantly 35-pass wipe your backups, cancel your Dropbox account, and block you from GitHb. (Page 46-47)
The book focuses on REST (Representational State Transfer) API development, but Sturgeon doesn't get too mired down in REST theory. He starts the book with a subsection on "endpoint theory" in which he discusses URL structure and what the various HTTP verbs mean (ex, PUT vs. POST); but, for the most part, Sturgeon focus on the actual implementation of the API (his examples are in PHP) and how to deal with inputs and outputs.
At the end of the book, he does have a chapter on HATEOAS (Hypermedia as the Engine of Application State), where he does dive down a little bit more into the theory of REST vs. real-world implementation:
While you often hear complaints like "but that is not RESTful!" from people about silly things, this is one instance where they are completely right. Roy Fielding says that without hypermedia controls an API is not RESTful, writing back in 2008. People have been ignoring that ever since, and the last estimate was that 74% of APIs claiming to be "RESTful" do not actually use hypermedia. (Page 147)
... but, to be clear, the meat of the book is much more focused on technical API development and avoids being overly pedantic.
I decided to re-read this book specifically because I've been working on an Angular 2 application and have been struggling with how to approach validation and error reporting. And, while the book doesn't look specifically at validation, it certainly covers error reporting from a perspective of HTTP status codes, application error codes and, the format of error responses. By getting a better of sense of what the client needs to see as an end-result, I was actually able to work backwards and come up with a better way to handle errors internally to my Angular 2 application.
Error code are usually strings or integers that act as a unique index to a corresponding human-readable error message with more information about what is going wrong. That sounds a lot like HTTP status codes, but these errors are about application specific things that may or may not have anything to do with HTTP specific responses.
Some folks will try to use HTTP status codes exclusively and skip using error codes because they do not like the idea of making their own error codes or having to document them, but this is not a scalable approach. There will be some situations where the same endpoint could easily return the same status code for more than one different condition. The status codes are there to merely hint at the category of error relying on the actual error code and error message provided in the HTTP respnose to include more information in case the client is interested. (Page 41)
I believe this book was written between 2013 and 2015, which in "internet years" is quite some time ago. That majority of this book is still quite timely. And, when I read it the first time, I didn't give it a second thought. But, re-reading over the weekend, one thing that popped out at me was the lack of any JSON Web Token (JWT) discussion. JWT is quickly gaining popularity in API development. But, the good news is, JWT is just another form of security and Sturgeon covers API security in the book. In fact, he already talks about passing OAuth "Bearer" tokens in the Authorization HTTP header; so, you can just substitute OAuth tokens for JWTs (unfortunately pronounced "jots") and everything else still makes sense.
Speaking of security, I thought Sturgeon made a particularly excellent point about passing access tokens around in the Header as opposed to the URL:
Headers vs. URL. You should always try to use the Authorization header to send your tokens whenever possible. The query-string is secured when using SSL, but unless they are intentionally blocked then access tokens could start turning up in server logs and various other places. Also, browsers will store the full URL (including query-string) in history. This could easily compromise the integrity of a user's security if their computer is stoken of if a sibling decided to play a prank. (Page 107)
Even beyond the scope of API development, thinking about how data may get logged is important for security. More than just access tokens, it's important to consider any Personally Identifiable Information (PII) that can show up in server logs or error logs. This goes beyond the topic of the book but, I enjoyed the holistic approach that Sturgeon used when looking at the API ecosystem.
One concern with just leaving all the security up to the network is that, if the network is breached, then hackers would be able to do rather a lot of damage. However, if hackers are 'all up in your networks', then you probably have a lot of security issues already. Keep it in mind. (Page 100)
Of course, I'm on the security team at work, so the security aspects of this book may be more interesting to me than your average reader.
Re-reading this book after recently reading "Production Ready Microservices" by Susan J. Fowler gave me a totally new perspective as I was going through Sturgeon's chapter on API versioning. In this book, Sturgeon basically says that all API versioning is problematic and that any particular approach to API versioning is just a calculated risk. Now, in Fowler's book on Microservices, she completely denounces any attempt to version at all. In her explanation, the world of microservices evolves so rapidly that the use of versioning creates an undue burden on clients and sets up an untenable microservice life-cycle. Of course, changes - including breaking changes - are an inevitability in the realworld; and, to that end, Sturgeon does outline several realworld approaches to API versioning, including the pros and cons of each approach.
This book was recommended to be me by my database administrator, Brad Brewer, and I'm definitely passing on the recommendation. Build APIs You Won't Hate is an easy read - it took me only a few hours to get through; but, it's a productive read that covers end-to-end API development.
Reader Comments