openSUSE:WebYaST REST Service Documentation

Jump to: navigation, search

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 -p 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
    Parameters in URL should be documented this way:
GET /path?param=<id>
   <b>id</b>: ID for ...
  • 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

= YaST REST Service Documentation

  Copyright © 2009-10 Novell, Inc.

  Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or (at your option) version 1.3; with the Invariant Section being this copyright notice and license. A copy of the license version 1.2 is included in the section entitled "GNU Free Documentation License". 

== System Service

  Only authenticated users are allowed to access the API. Authentication is done
  by sending a Basic HTTP Authorisation header.

  All names aren't allowed to contain spaces, slashes or colons.


== Table of Contents

Contents:

== Formats

  The system REST service supports only XML and JSON input/output formats.

== Overview

  This module provides access to the basic system component. Curretly it provides only reboot and shutdown actions.

  The module uses HAL as the backend, HAL daemon must be running to perform reboot/shutdown actions.

== PolicyKit Access Rights

  The following PolicyKit permissions are needed to execute reboot and shutdown:

  Reboot:   org.freedesktop.hal.power-management.reboot

  Shutdown: org.freedesktop.hal.power-management.shutdown

== System Actions


GET /system

  Get the list of supported system actions. The list contains actions like <i>reboot</i> or <i>shutdown</i>.

  CURL Example: curl -u user http://localhost:4984/system.xml

XmlResult: system


PUT /system

  Trigger a system action. Set active flag to true for the action which should be started - see the XML example file.

  CURL example: curl -u user -X PUT -H 'Content-type: text/xml' -d @reboot_request.xml http://localhost:4984/system.xml

XmlBody: reboot_request
  
XmlResult: reboot_response