API Descriptor Languages (i.e. I/O Docs, Swagger, RAML, Blueprint, etc.) can and should be used to not only provide interactive documentation and define APIs at the time of creation and testing, but also to help RESTful clients dynamically work with your API. In this talk from RESTFest 2014, Rob Zazueta explains how this should work. To see the actual talk, please see http://vimeo.com/108076468.

1. Descriptor Languages for Content Negotiation
Rob Zazueta
RESTFest 2014
Intel Confidential — Do Not Forward

2. The Problem
• Client programmers must write custom code just to access
and parse the data from most APIs.
• API testing tools can only go so far without writing
extensive, detailed test scripts.
• We’re not going to settle on standards any time soon.

3. The Solutions So Far
• Siren
• Hydra
• JSON-LD
• Etc.

4. WWBD?

7. What We Need to Make This Happen
• Move beyond the response format standards discussion – you just can’t
squeeze every domain model into a standard.
• Extend the purpose of descriptor languages – they’re not just for
documentation and testing anymore
• Start thinking in terms of resource-driven content types – Resources are
responsible for their state and their representation

8. Additional Benefits
• Saner versioning at the resource level – where it belongs.
• Truly responsive APIs – support as many or as few response formats as you
want from the same endpoint.
• Reaffirm the contract between client and server – embed your interactive
documentation into your API workflow.
• Focus on building great solutions – make it easier for client developers to use
your API.
• Better change management, reusability and composability – Truly match the
API models to your domain.
• Dynamic client generation – not just for code, but for a post-programming UI

9. Thank You!
Rob Zazueta
@rzazueta
rob.zazueta@intel.com
Shameless Plug – Please Check Out www.NARWHL.com