I’d also say that some options are better than others for a design first approach.

Thanks – I agree; both RAML and API Blueprint deserve mention – and there are quite a few Hypermedia related metadata initiatives as well…

/Ole

While they all attempt to expose metadata about a service or API, they not only do this in different ways, but rely on different optimizations. Service docs optimize the build experience (via proxy generation). Discovery documents optimize the runtime via configurability; essentially Discovery documents are consumed by a static runtime client. Both of these approaches favor “knowing” the entire set of possibilities are design/build-time.

Hypermedia is a runtime optimization based on _not_ knowing the entire set of possibilities. Hypermedia metadata is served up on an “as needed” basis – a very diff approach and one that continues to vex those attempting to create documentation for APIs.

Thanks for this! Regarding if links/actions are metadata or not – perhaps there is an academic distinction as you say, but personally I find that describing and providing available actions for a resource inline (as part of the response) or externally (for example in a swagger definition) is still the same “metadata” and there are pros and cons for each approach (maybe that would be a good follow-up post!?) – once again knowing your end users and how they will want to consume your API is crucial to making the right choice.

cheers!

/Ole