YaST/Web/Development/REST Service Documentation

From openSUSE

Documenting YaST REST Service API

This document describes how to write documentation for a YaST REST service.

Overview

WebYaST uses restility tool for generating documentation. It is available in package rubygem-restility.

The documentation is written is a separate plain text file which is converted by restility to HTML documentation. The generated documentation is stored in public/ subdirectory. This means that the documentation is directly available in the REST service.

Directory Structure in a Plugin

The documentation source is read from restdoc/api.txt file located in the plugin directory.

The problem is how to define the target path to the generated documentation. It must be unique for each plugin to avoid file conflicts and must be set in the plugin itself.

For this reason the output is generated into public/*/restdoc/ subdirectory - the rake task searches restdoc directory somewhere in public/ subtree. There should be just one restdoc directory (the first found is used).

Example: The system plugin documentation is available at http://localhost:8080/system/restdoc/index.html

Generating the documentation

There is a rake task defined for generating the documentation using restility.

Manual Generating

Call rake restdoc to manually generate the documentation. The documentation will be generated into restdoc directory.

Use this call when you are writing the documentation so you can immediately check the generated result.

Automatic Generating

The documentation should be automatically generated during package build. To enable automatic generation add these parts to the .spec file:

 BuildRequires:  rubygem-yast2-webservice-tasks rubygem-restility

 %build
 # create the output directory for the generated documentation
 mkdir public/controller_name/restdoc
 # build restdoc documentation
 export RAILS_PARENT=/srv/www/yastws
 env LANG=en rake restdoc

 # do not package restdoc sources
 rm -rf restdoc

These lines ensure that the RPM package will contain the uptodate generated documentation and the documentation source will not be part of the package. The documentation will be also regenerated when the restility package is updated.

What should be documented

A good example of a REST API documentation is the Twitter documentation.

The most important things to documents is

• The purpose of the module, what it can do - basic overview
• Is login required? (usually yes)
• Input/output format (usually XML and JSON)
• List of PolicyKit access rights, which rights are needed for reading, for writing...

Then, of course, the API itself should be described. Every function should have these attributes:

• The request type (GET, POST, PUT or DELETE)
• The URL path to the resource (e.g. /services/index.xml).
• Constrains - which values are valid, which options are mandatory or optional
• Special values - describe the special values (if applicable)
• Return values
• How errors or exceptions are reported

Format of the Documentation

Input format

Normal Text

The documentation text lines begins with at least one white space character (space or TAB). The text is not changed and it is possible to use HTML markup directly.

Supported Keywords

Here is the list of the supported keywords, the keywords must be placed just at the beginning of line (white spaces are not allowed).

• GET, PUT, POST, DELETE file_path - starts a new section (function), file_path is the path in URL
• Contents - this tag is replaced by the content section
• Host: host_name - specify a host for the service (useless for WebYaST, there is no single service URL)
• <parameter_name> : description - parameter description
• XmlResult: xml_file - XML result of the request, this generates a link to the XML file, xml_file is a XML file name without the .xml suffix
• XmlBody: xml_file - input in XML format, xml_file is XML file name without the .xml suffix
• Version: version - version of the API

Including XML Examples

XML output and input examples are placed in separate files. The advantage is that they can be easily created by curl and it is even possible to send them directly to a REST server to test them and verify that they are correct and work as expected.

Use XmlBody and XmlRequest keywords (see the previous paragraph).

See YaST Development Tips how to use curl for reading and sending XML files.

Example api.txt file

See the api.txt file in yast2-webservice-system module.