The way we design web APIs and write API docs is highly structured, natural to programmers, and wrong. HTTP API descriptions typically look nothing like the requests and responses they describe, and the underlying design often hides much ugliness. This creates extra work for the developer to understand the API, and figure out how to translate that to code. It also makes it harder to spot bad API design. Instead, you need more readable API documentation that doesn’t waste your time, and APIs that don’t get to hide their design flaws.

This presentation introduces Flat HTTP API Design (FHAD) - a better way to design and describe your HTTP API. FHAD API docs leverage HTTP’s own structure together with some layout and typography to document by example, in as much detail as you like. Attendees will learn to see API documentation in a new way, which they can use to write more effective documentation with less effort, and to design better APIs. More practically, attendees will learn which REST API design design mistakes to avoid from Dr Evil’s World Domination API.

Video

Slides

Presentations

• J-Fall 2018 - 8 November 2018