using descriptor languages for content negotiation in restful apis
DESCRIPTION
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.TRANSCRIPT
Intel Confidential — Do Not Forward
Descriptor Languages for Content NegotiationRob Zazueta
RESTFest 2014
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.
The Solutions So Far
• Siren
• Hydra
• JSON-LD
• Etc.
WWBD?
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
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
