Irresistible APIs: Designing web APIs that developers will love

by Kirsten L. Hunter

Summary

A Web API is a platform with a web-style interface developers can use to implement functionality. Well-designed APIs feel like a natural extension of the application, rather than just a new interface into the backend database. Designing Web APIs based on use cases allows an organization to develop irresistible APIs, which developers can consume easily and which support the business values of that organization.

Purchase of the print book includes a free eBook in PDF, Kindle, and ePub formats from Manning Publications.

About the Technology

It takes a village to deliver an irresistible web API. Business stakeholders look for an API that works side-by-side with the main product to enhance the experience for customers. Project managers require easy integration with other products or ways for customers to interact with your system. And, developers need APIs to consistently interoperate with external systems. The trick is getting the whole village together. This book shows you how.

About the Book

Irresistible APIspresents a process to create APIs that succeed for all members of the team. In it, you'll learn how to capture an application's core business value and extend it with an API that will delight the developers who use it. Thinking about APIs from the business point of view, while also considering the end-user experience, encourages you to explore both sides of the design process and learn some successful biz-to-dev communication patterns. Along the way, you'll start to view your APIs as part of your product's core value instead of just an add-on.

What's Inside




Design-driven development
Developing meaningful use cases
API guiding principles
How to recognize successful APIs
About the Reader



Written for all members of an API design team, regardless of technical level.

About the Author

Kirsten Hunter is an API evangelist who helps developers and business stakeholders understand, design, and deliver amazing APIs.

Table of Contents



UNDERSTANDING WEB APIsWhat makes an API irresistible?
Working with web APIs
API First
Web services explainedDESIGNING WEB APIsGuiding principles for API design
Defining the value for your API
Creating your schema model
Design-driven development
Empowering your developers

Genres: Programming, Technology, Software, Computer Science, Technical, Computers, Nonfiction

235 pages, Paperback

First published January 31, 2016

Reviews

[Sebastian Gebski · Rating 2 out of 5]

A book written be famous API advocate that is aimed at ... no-one?

Technical reader will be totally bored (e.g. with HTTP basics) - this book doesn't get much further than what is Swagger, RAML & OpenAPI. What is more, there are plenty of "companion-concepts" that are generally well known (e.g. DDD, Agile, Kanban, ...) & honestly do not bring much value into the topic.

Business / Domain reader will be taught / reminded that API should be considered a product & the best APIs are the consumer-driven ones, but ... that's about it. Some easy technical concepts (mentioned above) that are not really crucial for a business person.

This book doesn't describe well what is an "irresistible API", it doesn't provide many applicable techniques or hints (except from some high-level ones), so the only reason for 2nd star are some brief (but quite interesting) use cases from companies that tried various approaches to APIs (with different results).

Real disappointment & one of the worst Manning books ever.

[Aleksej · Rating 4 out of 5]

Nice, mostly non-technical introduction to API world.
It's not only about development, but about the whole lifecycle of an API including design, documentation, etc.
Would recommend for beginners in the space.

[Zbyszek Sokolowski · Rating 3 out of 5]

The book is written by Kirsten Hunter who is an API evangelist who helps developers and business stakeholders understand, design, and deliver APIs. The book is intended to all members of an API design team, regardless of technical level.
Irresistible APIs is not bad book per Se. However when sometime ago my friend experienced Java developer was surprised why book related to webAPI has so may pages, at that time I was thinking that he only concentrate at technical part and there the topic is not so narrow. After reading the book I see that he was right to some extent. First the author describes basics of REST API in quite nice way. Then book suddenly starts it prolonged advocacy part.

The book is not so technical, there are a lot advocacy in it and good arguments why approach API First is so important. This is in this context very good book for Architects, Project Managers and so on. Author explains why API added as extra feature is a very bad design decision. And also there are examples from business point of view describing how good and bad decisions had influence on companies like Netflix, Twitter etc. Of course it is very valuable from business point of view and advocacy. Agreeing with all of that I was reading next pages seeking when "the meat" part eventually will start. And it passed more than half of book with that advocacy style. Of course everything towards understanding how important creating of good API is. For companies for their third party clients and so on. I can agree with everything but it is pretty verbose.

Then author describes how to create good APIs and she proofs that using good user cases/stories is good approach, again agree. Then she introduces several designing API schemas tools like Open API (Swagger). In book there are several exercises which are intended to put reader hands on practical subject which is good. In case of using schema designing frameworks it lacks points where user is generating stubs and can use it.

Then she provides quite good guidelines how to prepare good support via documentation, forums and so on.

Then authors starts to pack in a stuff which seems to be only to increase volume of book. So describing methodology like DDD, waterflow, agile and so on.

This is yet another book when I have impression that would be better if it had less pages, be less verbose and to the point. And I would like to have impression. Yes I spent a lot of time with book but I've learned a lot. I have grown.
Here from technical point of few there is a lot to add. From advocacy yes I've learned a lot of arguments why good API is crucial.

Some quotation:

First, in REST APIs, a request using the GET method should never change the data on the server. One reason why this is important is that if your API doesn’t follow this rule, a web crawler or other automated system could accidentally change or delete all the items in your system.

Thinking of your main product in terms of API features that might be useful is an effective way to start thinking about what use cases you want to support.

Modeling schemas for REST APIs isn’t necessarily an easy task; making sure that different products are presenting the same information in the same way is something that takes time and work. For instance, an endpoint associated with accounting and reporting might present a “user” and his or her accounting information differently than the document management system, which would show ownership and editorial information. This process helps you to avoid those clashes during development and meet your deadlines with a minimum of difficulty. Back-end systems usually keep all this information segregated, but when designing an API you should think of your data as items within a cohesive system rather than distinctive items within separate systems. This is one of the main guidelines that is frequently missed when API design is left to back-end architects, who are generally focused on scalability, performance, and precision as opposed to usability. Your API design should include a human-readable definition for each endpoint; the methods, fields, and formatting for the response; and any other metadata that’s important within your system.

Back-end systems are usually designed to meet specific needs, and unless the API is designed for a consistent developer experience across all interfaces, the developer may have to spend an inordinate amount of time trying to figure out what’s available and how the application can retrieve it from the platform.

Mobile application developers were frustrated that they had to make multiple calls to render a single screen—an antipattern that makes mobile applications fragile and nonperformant (users tend to walk into elevators or drive into tunnels, and it’s important that the application can get the information it needs efficiently).

An important thing to realize in this case is that when you’re asking multiple business units or teams to come together and work as a larger team, you need guidance, vision, and support from both the high-level executives (the refactor won’t generate new revenue on its own) and from an architecture team who can review the new APIs as they’re created to make sure they’re in line with the goals of the overall platform strategy.

consider the experience of the developers using the API. It’s often tempting to try to focus on scalability and performance, but the basic truth of this is that if you don’t focus on usability, you’re not going to create a usable API, and nobody is going to use it—at which point scalability and performance aren’t going to matter to anyone.

Second, and even more important, using a nonstandard approach creates a situation where developers are quite likely to use the API in a way you don’t expect or support as they try to figure out the right way to interact with your system.

For various reasons, such as the mobile case described earlier, you’ll probably need to move away from the strict REST philosophy in order to best serve the needs of your users.

When developers are initially exploring your platform, the questions they’re likely to ask are “What can I do with this?” and “How do I do something?” Unfortunately, most documentation for APIs focuses on “How does this work?”

First, developers who are new to your system and find it through spelunking on the web may well not know what they want to do with the API. Making the assumption that they do know means that developers who aren’t already familiar with the data space and why they want to use it will likely give up and leave.

A schema model is a contract describing what the API is, how it works, and what the endpoints are going to be. Think of it as a map of the API, a user-readable description of each endpoint, which can be used to discuss the API before any code is written. Like a functional specification, this document describes how the API will behave. Creating this model before starting development helps you ensure that the API you create will meet the needs described by the use cases you’ve identified.

functional specification standard for software projects. If you don’t, your product managers need to create a document that, at the least, answers the following questions: What problem is the project solving? What is the business value? What are the metrics and use cases? What resources are needed or available? What does “done” look like? What could go wrong?

Targeting a subset of endpoints also makes it possible for you to split the team into two subteams, one working on each set of endpoints. Knowing that you have a schema model can give you confidence that the two teams won’t diverge while creating the API.

The types of documentation you need to have are as follows: Reference documentation— “What does it do?” This is the documentation you’re probably expecting to need. You’ll be answering more specific questions such as “What does each endpoint of the platform do?” “How does a developer call it?” and “What is the expected response to a call?” Workflows— “How do I do something with the platform?” This type of documentation tells a developer how to achieve specific tasks using the platform. Tutorials— “How can I get started?” These tutorials should take your specific targeted use cases and create step-by-step guides for developers to follow in order to get started using the system, or achieve common, simple tasks. Usually the tutorials you should include are the most important items from the workflow list.

HTTPie—HTTPie was recently written as a command-line alternative, and it’s strongly tied to API calls. JSON responses are formatted well, with color coding and indentation. Writing an authentication plug-in is relatively easy, and because of this several HTTPie authentication plug-ins are available. It’s open source, free, and definitely worth including in the documentation as an easy way to interact with the API from the command line.

[Adam · Rating 3 out of 5]

In general, I wish this book could be more concrete and tailored to a certain type of reader. If you are a developer as I am, you may become bored pretty fast, since there is not much in here than simple HTTP and REST basics (Chapter 4. Web Services Explained) or schema modeling with RAML and OpenAPI (Chapter 7. Creating your schema model). Sadly, all of it is very shallow and IMHO may be interesting material for a total API newbie, but not for a person who worked with at least one API.

I read this book cover to cover, trying to find a part that is truly interesting, but unfortunately, nothing caused the wow effect. This book advocates API First design, presents use cases and success/fail stories from companies like Netflix, LinkedIn, Facebook, Akamai, Twilio etc. It tries to draw your attention to writing good API documentation, related tutorials and in general, make your API consumers happy.

I feel like I could condense all of this 325 pages novel into 50-70 pages and save readers time. My advice is, just pick up the chapters that resonate the most with you. If you try to study it cover to cover as I did, you may get a similar feeling of learning everything and nothing...

[Juan González Núñez · Rating 4 out of 5]

Knowledge Level: Basic - Intermediate
Audience: Whoever wants to know more about APIs. Managers, Tech Leads, Developers, QA, etc.
Review: Explain the concepts, types, and technologies involved in APIs. Use real-world examples to explain what happened to companies when they use bad or best practices to implement them.
Lessons Learned: Pillars of DevEx: Communication, Documentation, Building Blocks, and Support

[Yannick Grenzinger · Rating 3 out of 5]

If you're discovering the world of product as API, this is a good book offering a broad view of why and how to develop an API from product management to typical best practices but also other important subject like documentation and developper experience.

But sadly, it's not the book you are looking for if you already have an experience around (REST) API and are looking for a deep approach on the subject like the most advanced way to do REST (like hypermedia and beyond)

[Adam · Rating 4 out of 5]

Will be using many of the pointers.

Second half reads more like a general practice guidance, while first half gives more specifics to APIs

[Cezar Halmagean · Rating 5 out of 5]

A very nice, high level overview for creating and managing APIs.

[Andrew · Rating 3 out of 5]

A good overall introduction to API design, though it seemed to lack focus and would veer into discussions around development methodologies.

[José · Rating 3 out of 5]

Good intro to APIs and summary of a workflow on how to implement them, very little technical advice though. Look like it is more oriented for project managers than developers.

[Farzin]

[]

[Adam Smith · Rating 4 out of 5]

Good introduction to API's, but the last few chapters were redundant and off-topic. Overall a good read.

[Sahil Sharma · Rating 2 out of 5]

Not what the title suggested. A nice introduction however a great APIs require a lot of effort in its modelling schema which is skimmed in the book.

[Dayton Outar · Rating 5 out of 5]

This book is very quick and easy read.

[Michal Paszkiewicz · Rating 3 out of 5]

http://www.michalpaszkiewicz.co.uk/bl...

[Ahsan Sharafuddin · Rating 3 out of 5]

The author is an API evangelist, hence the book is more verbose than technical. However, if you are technically inclined you'll get a modest encounter with RAML and Swagger (OpenAPI). It'd be nice to include 'Blueprint' too. Unfortunately for someone like me, who has a voracious appetite for technical info, it was kind of "meh".

[Orn Solmundsson · Rating 3 out of 5]

The books starts well by describing APIs and what makes a good API. I would have liked more detailed descriptions about the main content which is APIs. The bad parts about this book is that it makes an effort to explain Agile methods, like Scrum, Kanban and other, I would personally like to read about Agile in other books. Links to more content and further reading are missing.

[Adam · Rating 5 out of 5]

Irresistible APIs is really good. Plenty of (good) examples including a few real world examples of bad APIs / API decisions.

Guidelines, antipatterns, business values, API-first, design-driven dev, schema modelling, DX. Just wish there was more about authentication.

I'd recommend.

[Johnny · Rating 4 out of 5]

Many good points on what it takes to make a well designed and developer friendly API. Not jet finished, but it already helps you to prevent the most common pitfalls.

[Ryan · Rating 4 out of 5]

Really well-done introduction to APIs. Contains some very well-thought-out recommendations on the development process.