Principles of Web API Design
Delivering Value with APIs and Microservices
Delivering Value with APIs and Microservices
James Higginbotham
brings together principles and processes to help you succeed across the entire API design lifecycle. Drawing on extensive in-the-trenches experience, leading consultant James Higginbotham helps you align every stakeholder on specific outcomes, design APIs that deliver value, and scale the design process from small teams to the entire organization.
A common question you'll find on any software development forum is "How to start developing a web api" and predictably the answers will come from other developers touting the benefits of using some framework or programming language over another. Undoubtedly the thread will continue in various flame wars on and undoubtedly all the issues developers experience in developing Web APi's will end up with a Godwin point being awarded and everything being blamed on Hitler.
The reality is the answers to these question never really answer the real question and inevitably end up in many organisations never really truly developing an API and all they ever end up with is a load of fragmented functions available over HTTP requests.
The primary issue, is that developing a truly functional and proper Web API takes a lot more than just firing up a new project in your code editor based on some project template. An excellent quote from the book sums up the situation perfectly.
When code is seen as the one and only tool to design an API, the quality of the API design can suffer
The Principles of Web API design
Why I read this book
As a contractor, I have seen my fair share of really poor implementations of Web API projects where it has become blatantly obvious that the design and implementation of the API was left too the developers and the majority of the API was developed to support just the one front end application because there was no hope in hell it could be consumed by anything else.
This has been the case for a number of years and has encompassed a wide range of come and gone technologies like SOAP, WCF, RPC, Remoting and probably many more. Implementing an API is nothing new, in fact it's probably as old as computing. The issue is that developing a good API takes a lot more than just writing code.
I was looking for a process or methodology I could follow to improve the process of API design and try put an end to this recurring problem I witness out in the wild of failed API projects in the wild.
For the most part the author focuses on REST, presumably because it is probably the most popular and common implementation for Web APi's. However he does provide coverage for GraphQL, gRPC etc, but it is important to realise that these are minor implementation details as far as delivering the API, the more intensive and probably the most value tasks are the Design and Refine processese.
What I like about this book
First of all I have to say I really enjoyed this book, in the respect that despite it being a text book it was still an extremely easy read and not overwhelming. However, at the same time it is jam packed with extremely useful and relevant information, that can be effectively applied.
I think the author does a great job addressing and providing the relevant information needed to deliver effective web API's. Spoiler alert, that audience is not exclusively software developers. The information in this book will be of immense value to a number of roles in a project. Business Analyst, Product Owners, Project Managers, Quality Assurance etc.
I've read through the book cover to cover in a week, and I refer to frequently and consider it an invaluable resource.
One of the most useful and pragmatic tools I have takne from this book, is the idea of writing Job Stories to help define your API.
Job Stories capture the jobs to be done for any product, including the customer motivations, events and expectations for a new product, service or API. They frame every design problem from the perspective of the customer. Job stories seek to identify the problems that customers have and the eventual outcome they wish to achieve. API's will offer digital capabilities that will power the Jobs To Be Done (JTBD) .
This book lead me on to explore the JTBD methodology further, and it has become my preferred process for defining functionality. In short, JTBD are like user stories but only better. For me personally I just find thinking and writing using the When .....I want to ... So I can ... so much easier and intuitive than the Given...When... Then structure of user stories.
On the whole the book offers a product-led approach to sepcifying, designing and delivering API to the market. The book provides details on how to implement ADDR Process (Align Define Design Refine) which some may view as simialr to Build Measure Learn (BML) Loop form the Lean Startup, but it has a slightly more technical focus and the ADDR process can fit it quite easily withing BML loop
The Lean Start Up
How Today's Entrepreneurs Use Continuous Innovation to Create Radically Successful Businesses
The Lean Startup is a new approach being adopted across the globe, changing the way companies are built and new products are launched.
Why I recommend this book
Building a successful Web API is less about the technology implementation and more about perfecting and improving the process of preparing, defining and execution of the effort. This book does not get lost in the superfluous implementation detail or getting lost in any particular programming languages. The book also doesn't provide any platform specific advice or even try guide you down any preferred vendor approach, so there is nothing about Delivering, Maintaining an API on cloud platforms.
However, this book does guide you on how you and your team can make those important decisions, which from experience is 80% of the real effort and actually the stuff that matters.
The book does contain some code samples, but really they are only JSON, YAML and details of various HTTP methods, requests and headers, which should be easily understood by all.
This book makes a great companion read for API Design Patterns , which provides additional technical design principles and best practices to follow when developing web API's
API Design Patterns
API Design Patterns lays out a set of design principles for building internal and public-facing APIs. Providing a collection of best practices and design standards for web and internal APIs.
Principles of Web API Design
Delivering Value with APIs and Microservices
Principles of Web API Design brings together principles and processes to help you succeed across the entire API design lifecycle. Drawing on extensive in-the-trenches experience, leading consultant James Higginbotham helps you align every stakeholder on specific outcomes, design APIs that deliver value, and scale the design process from small teams to the entire organization.
- What is this Directory.Packages.props file all about? - January 25, 2024
- How to add Tailwind CSS to Blazor website - November 20, 2023
- How to deploy a Blazor site to Netlify - November 17, 2023