Browse Prior Art Database

RESTful webservices documentation

IP.com Disclosure Number: IPCOM000240205D
Publication Date: 2015-Jan-13

Publishing Venue

The IP.com Prior Art Database

Abstract

This publication defines a markup for documentation of REST APIs. It makes use of tags embedded in the webservices which are read by a parser and used to output a WADL containing the REST API definition.

This text was extracted from a PDF file.
This is the abbreviated version, containing approximately 15% of the total text.

Page 01 of 20

RESTful webservices documentation

RESTful APIs are gaining popularity as a means by which a web service can be invoked. The documentation of these web services is a critical component for users who consume these APIs, however there are various problems which are encountered around writing and maintaining the documentation of these APIs. Some of these problems are as follows:

Easily keeping the documentation up to date and accurate to the implementation of the web service.

Ensuring the documentation is easily consumable to the end user.

Making the documentation easy to update for the developer

Documentation tools do not usually contain fields which are targeted towards REST APIs

Automated generation of documentation often introduces requirements and changes to the web services implementation

There are many tools which can be used to automatically document code. However none of them address all of the problems listed above. In some cases requirements are imposed and implementation changes need to be made for generation of documentation to be possible . Or they simply cannot document the service effectively with the provided constructs.

The core idea of this invention is to include within the code, as comments, meta-tags which are used to describe the web service which is being implemented. An interpreter can then be used to parse the meta-tags and convert them into a WADL file(Web Application Description Language)[1], which is an XML based definition of a RESTful web service. This XML file can then be transformed into a human readable format using XSLT and CSS.

The following diagram illustrates the concept:

1



Page 02 of 20

The idea of creating self documenting code, and producing end user documentation from this code is not novel. This disclosure however is

2



Page 03 of 20

specifically geared towards RESTful web services and defines the specific markup which will appear in the code to generate the WADL files .

This approach has the advantage of:

Specifically targeting RESTful web services, making it easier to document these types of services.

Keeping the meta-data with the relevant code so that it can be easily kept up to date as changes are made to the web service.

Documentation is authored by the person who is most familiar with the web service and has the most technical expertise .

This doesn't introduce any requirements on the implementation itself as all meta-tags are implementation independent.

The XSLT and CSS can be customised to change the look and feel of the end user documentation. This does not impact the meta-tags within the code.

WADL[1]: http://www.w3.org/Submission/wadl/

The Following is the full specification known as RAPI doc(short for restful api documentation).It describes the meta-tags which need to be added to the code. It documents the specification of the markup language. It does not include the tool which is used to convert these tags to WADL format or the XSLT and CSS used to transform the WADL to human r...