Validation and Interactivity of Web API Documentation

Many Web APIs (by which we mean ones using HTTP as the application protocol) 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.

[1]  Roy Fielding,et al.  Architectural Styles and the Design of Network-based Software Architectures"; Doctoral dissertation , 2000 .

[2]  John Domingue,et al.  Investigating Web APIs on the World Wide Web , 2010, 2010 Eighth IEEE European Conference on Web Services.

[3]  Roy T. Fielding,et al.  Uniform Resource Identifier (URI): Generic Syntax , 2005, RFC.

[4]  M. Lothaire,et al.  Applied Combinatorics on Words , 2005 .

[5]  Wu Chou,et al.  Design and Describe REST API without Violating REST: A Petri Net Based Approach , 2011, 2011 IEEE International Conference on Web Services.

[6]  Ivan Herman,et al.  RDFa Core 1.1 , 2010 .

[7]  Alon Zakai.  Emscripten: an LLVM-to-JavaScript compiler , 2011, OOPSLA Companion.

[8]  Amit P. Sheth,et al.  SA-REST: Semantically Interoperable and Easier-to-Use Services and Mashups , 2007, IEEE Internet Computing.

[9]  K. Gebbie,et al.  What's hot, what's not. , 1999, The AIDS reader.

[10]  Gary Court,et al.  JSON Schema: core definitions and terminology , 2013 .

[11]  Roy T. Fielding,et al.  URI Template , 2012, RFC.

[12]  Tomas Vitvar,et al.  hRESTS: An HTML Microformat for Describing RESTful Web Services , 2008, 2008 IEEE/WIC/ACM International Conference on Web Intelligence and Intelligent Agent Technology.

[13]  Roy T. Fielding,et al.  Uniform Resource Identifiers (URI): Generic Syntax , 1998, RFC.

[14]  Paul J. Walmsley,et al.  XML Schema Part 0: Primer Second Edition , 2004 .

[15]  Roberto Chinnici,et al.  Web Services Description Language (WSDL) Version 2.0 Part 1: Core Language , 2007 .

[16]  Erich Schikuta,et al.  On the Origin of Services Using RIDDL for Description, Evolution and Composition of RESTful Services , 2010, 2010 10th IEEE/ACM International Conference on Cluster, Cloud and Grid Computing.