API Strategy & Practice Conference 2018

The Open API Spec and other API description formats have made a big impact on API designers and consumers. While they've improved how machines talk to each other, they have missed some important human opportunities in APIs. Machines need to think in endpoints, while the human who sees the results of an API call thinks in use cases.

Running over 1,000 APIs in production for millions of users makes the human side of API clear. They want to pull new contracts from their CRM or add new orders to a shopping cart. In some APIs it may take multiple endpoints to fulfill a use case. And there are almost always endpoints that meet a machine need and don't support users directly.

In this entertaining talk, API veteran Adam DuVander will share how far we've come with API descriptions, examples of how they're missing human needs, and some ideas to bring use cases into our API description workflows.