Validation and Interactivity of Web API Documentation

Many Web APIs do not publish a machine-readable API description (in a language such as WADL or WSDL) but only provide human-readable documentation, usually in HTML. This documentation may be machine-generated, or it may be hand-edited in which case there is the possibility of errors being introduced into the API description. In this paper we present a Web Interface Language (WIfL) vocabulary for API documentation, which is intended to be embedded in HTML using RDFa annotations. We present the semantics of WIfL, including a formal presentation of inheritance and validation. We discuss our WIfL tools, which include a dynamically generated console for interacting with an API's reference implementation, and a validator which can check an API for internal consistency.