openSUSE:WebYaST REST Service Documentation
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