Spring I/O

Sessions

Oliver Gierke

Documenting RESTful APIs with Spring REST Docs and RAML

Oliver Gierke - Pivotal

Most APIs built today are considered REST APIs these days, when in fact they merely exchange data via HTTP and JSON. At the same time, systems almost never act autonomously but rather live alongside others. In that context, being able to evolve an API becomes a crucial aspect in its design and the only knee-jerk, but often problematic reaction usually is: versioning.

The talk takes a step back and looks at the architectural context APIs live in and outlines the drawbacks that result from ignoring crucial parts of REST. It discusses internal VS. external APIs, the impact of Domain-Driven Design and how to design and specify APIs and their clients to optimize for evolvability so that changes in an API don’t break clients.