This is a review of Phil Sturgeon’s book Building APIs You Won’t Hate.
Building APIs You Won’t Hate
A bit of an edgy title, isn’t it? It makes sense, though. The potential of a developer hating anything he built given enough time to work on it is enormous. It’s an inverse parabola of sorts – your enthusiasm will grow for a given amount of time, and then proportionally drop until you sink below the starting point of pleasure. If you push through this depression, learn new techniques, and then apply them to your work you get a kind of sine wave in which your enthusiasm again rises until it starts dropping, and so on and so forth.
This book tries to help you make the climb along the parabola last as long as possible – its aim is to teach you some API development practices which make your APIs simpler, more robust, and more “people-who-are-not-you”-friendly.
Writing Style and Audience
Phil remains true to himself in a manuscript filled with humorous remarks, snarky comments, and practical examples. The chapters are well structured and fluidly presented with content breaks in just the right places, never making the book overwhelming or frustrating.
The audience of the book is, I would argue, intermediate and senior level developers who want to improve their existing design or just seek advice on how to get started with proper API development before they turn it into a mess they’re already expecting it to be. You will have little to no use of the book if you’re a junior, but maybe buying it and keeping it in your Leanpub shelf wouldn’t be a bad idea for when you’ve got a couple more notches on your PHP club.
The one downside is that Phil can’t spell to save his life. And not just typos and the occasional apostrophical butchery:
but also the cringeworthy grammar and at times milk-curdling phrasing. In typical Leanpub fashion, this is where the need for a professional editor really becomes obvious. Indie authors, I’m absolutely certain you know someone who studied English in at least some regard (and was relatively good) – ask them to read your work and correct it during writing, it’ll help loads. If you can’t find anyone, pay someone! Heck, I’ll do it for free, just send me your books.
This, though, is the only gripe I have with the book.
Technical Aspect and Content
Technically, this book excels on almost all levels.
The content is evergreen and bound to stay relevant for a while, with only the occasional reference to irrelevant operating systems and their package managers (OS X, Homebrew). These parts would have been better if replaced with a common Vagrant setup like Homestead or Homestead Improved in the book’s introduction, then demoing all further examples on it. Such an approach would have made the code parts more approachable to all readers, even keeping their URLs consistent, removing the need to mention home directories, example domains, etc. It’s a minor potential upgrade with a relatively minor positive reading flow effect, but still a potential upgrade.
As someone who deals with other people’s APIs daily and is working on his own, I could appreciate all the tips within. Not only does Phil go out of his way to recommend excellent accompanying tools to use during development and debugging (and show their basic use), his examples are all real-world and based on his experiences working on a heavy duty API.
Almost every chapter lists common approaches in designing a specific feature of an API and ends in a comparison of their pros and cons, usually culminating in the approach Phil took and preferred during his adventures. I found the authentication chapter particularly interesting, as that’s the only aspect of API development I’ve ever had problems with, though I would have preferred it to touch a bit more on the topic of ACL and role based control through the API request itself.
Having been published a while back, the book’s Documentation chapter is missing RAML as an option, but the chapter is so filled with practical instructions and step by step examples it doesn’t even matter – learning on a practical, real world example of documentation far outweighs the benefit of just hearing about a newer concept.
Content-wise, the only missing chapter is “Caching” and Phil acknowledges this in the book’s outro. Caching within the context of API development is an incredibly powerful topic, one I enjoyed hearing about in one of Ross Tuck’s talks at ZgPHP, and I do hope it’ll be added soon.
Conclusion
I’m giving the book a 4/5 with an elephpant killed off just because of the spelling and grammar and maybe a little bit because of the missing Cache chapter.
All in all, this book is a gold vein chock full of nuggets of valuable information and if you’re considering building an API for whatever purpose, give it a read. By the way, you can get it cheaper now – by using this link, the first 100 customers get a big discount.
Did you read it? What did you think?
Frequently Asked Questions (FAQs) about Building APIs
What are the key principles to consider when building APIs?
When building APIs, it’s crucial to consider principles such as simplicity, consistency, and flexibility. Simplicity ensures that your API is easy to understand and use. Consistency in naming conventions, error handling, and response status codes enhances predictability and usability. Flexibility allows your API to evolve and adapt to changing requirements without breaking existing functionality.
How can I ensure my API is user-friendly?
To ensure your API is user-friendly, provide clear and comprehensive documentation. This should include detailed explanations of how to use your API, example requests and responses, and information about error handling. Additionally, use intuitive and consistent naming conventions and provide helpful error messages to guide users.
What is the role of versioning in APIs?
Versioning is a critical aspect of API development. It allows developers to make changes or improvements to the API without disrupting the existing functionality. This is particularly important when the API is used by third-party applications, as changes can potentially break these applications if not properly managed.
How can I handle errors effectively in my API?
Effective error handling in APIs involves returning meaningful error messages and appropriate HTTP status codes. This helps users understand what went wrong and how to fix it. Additionally, consider providing a unique error code for each type of error, which can be referenced in your API documentation for further information.
What are the best practices for API security?
API security is paramount to protect sensitive data and prevent unauthorized access. Best practices include using secure protocols such as HTTPS, implementing authentication and authorization mechanisms, and regularly testing your API for vulnerabilities.
How can I test my API effectively?
Effective API testing involves testing all aspects of the API, including functionality, performance, security, and error handling. Use automated testing tools to ensure thorough and consistent testing. Additionally, consider using mock data to simulate different scenarios and edge cases.
What is the importance of pagination in APIs?
Pagination is important in APIs to manage large amounts of data. It allows users to retrieve data in manageable chunks, rather than all at once, which can improve performance and usability. Implement pagination by providing parameters for the number of items per page and the page number in the API request.
How can I design a scalable API?
Designing a scalable API involves considering future growth and changes. Use flexible data structures and avoid hard-coding values that may change. Additionally, ensure your API can handle increasing amounts of traffic by optimizing performance and using scalable infrastructure.
What is the role of caching in APIs?
Caching can significantly improve the performance of your API by storing and reusing frequently requested data. This reduces the load on your server and provides faster responses to users. Implement caching strategies based on the nature and frequency of your API requests.
How can I ensure my API is maintainable?
To ensure your API is maintainable, write clean and understandable code, follow consistent coding standards, and provide comprehensive documentation. Additionally, use versioning to manage changes and improvements over time without disrupting existing functionality. Regularly review and update your API to address issues and adapt to changing requirements.
Bruno SkvorcBruno is a blockchain developer and technical educator at the Web3 Foundation, the foundation that's building the next generation of the free people's internet. He runs two newsletters you should subscribe to if you're interested in Web3.0: Dot Leap covers ecosystem and tech development of Web3, and NFT Review covers the evolution of the non-fungible token (digital collectibles) ecosystem inside this emerging new web. His current passion project is RMRK.app, the most advanced NFT system in the world, which allows NFTs to own other NFTs, NFTs to react to emotion, NFTs to be governed democratically, and NFTs to be multiple things at once.
