J-Fall 2018: Peter Hilton – Flat HTTP API Documentation
The way we write API docs is highly structured, natural to programmers, and wrong. HTTP API documentation typically looks nothing like the requests and responses it describes. This creates extra work for the reader to understand the documentation structure, and figure out how to translate that to code. It also makes it harder to spot bad API design. Instead, you need more readable documentation that doesn’t waste your time.
This presentation introduces Flat HTTP API Documentation (FHAD) – a better way to document your HTTP API. FHAD leverages 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 immediately to write more effective documentation with less effort. You’ll also get a REST API design checklist that you can use to either document or avoid design mistakes.
Peter Hilton is a software developer, writer, speaker, trainer, and musician. Peter’s professional interests are business process management, web application development, functional design, agile software development and documentation. Peter currently consults for Signavio in Berlin, and delivers the occasional presentation and workshop.
Peter’s software development interests include process management, web applications, service architecture, software development methodology and practices, and web-based collaboration. Peter has presented at numerous European developer conferences. Peter co-authored ‘Play for Scala’ (Manning Publications) and has taught ‘Fast Track to Play with Scala’.
