Email the Author

About the Book

APIs have increased in popularity substantially over the last decade, from people just starting to build "the API" for their company,all the way to now where even small teams are building out multiple APIs and getting into distributed architectures with microservices. Many folks start building and building and after they have a few services in place they realize that everything is a mess and nobody knows what they are dong. We've all been there; somebody you didn't know changed a field you didn't know existed in an API you have never heard of, and now the men in suits have come downstairs to see why their company is on the news because of downtime issues in Australia mean nobody's keycard is working so nobody can use the bathroom.

Eventually a new tool pops up which promises to help with all those problems and people rush to rewrite everything in that tool, creating brand new terrible design decisions and losing all the valuable learning's from the last previous mistakes.

Let's fix this cycle, by focusing on API theory in general, and then zoom in on how these things are done in HTTP in general, REST, GraphQL and gRPC - three popular approaches to building APIs right now.

The book is broken into five parts:

1. Theory
2. Planning & Design
3. Building & Testing
4. Management & Experience
5. Further Theory

The theory section will teach you a lot about API development in general, without tying your knowledge to a specific tool (tools change!) Learn about how HTTP/2 and HTTP/3 change API development entirely. Never heard of HTTP/3? Yeah! Many developers have only heard of HTTP/2 in passing, but it changes everything about API development.

Then we get into designing APIs using description formats like OpenAPI and AsyncAPI, using GUI editors to easily create description documents. These description documents can be used to create realistic mock APIs for folks to play with and confirm things work right before you start wasting your time writing code incorrectly. Design first is a beautiful thing.

Building and testing will very briefly help you pick the right collection of tools to put together to achieve the functionality you need, with examples in a bunch of different languages, before very quickly moving onto testing. The concepts of testing will last forever even though the tools change, so spending more time there will allow you to swap out the building blocks and keep on developing for a long time.

Management and developer experience could almost be its own book, the world of API Gateways are crucial these days, to avoid you repeating a bunch of cruft between all your APIs, leading to pointlessly inconsistent authentication experiences, different rate limiting policies, etc. The practices needed to make a good Developer Portal are haaaaaaaaard, but very important if you plan on opening your API to the public. Learn how these things can all fit togehter, with Governance coming into play to help ensure quality.

There's gonna be a lot of stuff in this book folks. My fingers may never be the same again.

About the Author

Phil Sturgeon

@philsturgeon

Instagram

Since 2010 I've worked as a freelancer, consultant, API lead, and CTO for several API-centric technology startups. Working as an internal API consultant for WeWork gave me a lot to write about, where I used my experience of things going horribly horribly wrong to help educate developers, define standards for API design and architecture, and implementing full API design lifecycles so we weren't all just building nonsense and hoping it was useful.

Trying to get loads of different questionably built APIs tidied up, playing nicely, and working quickly was a constant source of learning for me and everyone involved. I took a lot of that learning to Stoplight, and helped plan, build, and manage most of your favourite OpenAPI tools.

When I'm not banging on about APIs I'm riding, racing, or crashing various bikes, or saving the plant through Protect Earth, an environmental charity I co-founded in 2020. We create brand new woodlands, restore and extend ancient woodlands, and run around with machetes getting rid of invasive species.