API Documentation

The application can expose it’s APIs in a public domain. The documentation of the API can be easily generated through the aalam packager and will be accessible from the apps server from the the application’s page.

The application can write the documentation in a specific format as the docstring in the action handler of a URL. The URL action handlers which does not have a docstring will not be documented.

The documentation covers the information about the list of permissions needed for an API as well.

Docstring Format

Doctring should simple contain the following items

• Title
• Description
• Section
• Params
• Input
• Output
• Hook-Input

All the items should be indented at the same level.

Title should be the first item and the second item should be Description. Other items can be in any order.

Except Title and Description, all the other items are optional. There should be an empty line break between two items. For example,

"""
This is title

The description goes here, and it will usually be long
"""

You can notice the empty line between title and description. The empty line is essential to inform the parse about the end of an item and the start of a new item.

Except Title and Description other items should start with their name followed by a colon :, and they are called named items For example,

"""
This is title

The description goes here.

Params:
"""

Params and Section items can occur only once. If they occur multiple times, the last one will be used.

Of the named items, except Section, all the other items should have a sub items, which are just key value map. Section item accepts a string value directly.

All the sub items should be indented at the same level. There should be no empty line between the sub items.

The values for any item can be single line or multiple lines. If the value is of single line, it can be in the same line as the key. Else the value should start from a new line. If the value starts in a new line, it should be at an indentation level greater than the key.

For example

"""
Title

Description goes here, it can be of multiple lines.
This too is a description. Description can go on for many lines
till an empty line

Section: One-line Value

Params:
    sub-item-1:
        This is the value for sub-item-1.
        Notice the indentation level of this line and the previous line.
        It is greater than the indentation for sub-item-1.
    sub-item-2: One-line value
    sub-item-3:
        One line value in new line, notice the indentation level.
"""

Title

The first line of the docstring should be a title for the API. The title should fit in one line usually in two or three words. Title should give an overview of what the URL does. For example for method GET /aalam/base/users the title can be “Get users”.

Titles can be accessed by url fragments, so keeping it long will make it unappealing.

Description

A complete description of the URLs functionality. You need not document about output/input/parameter/permissions in this area.

For the above title “Get users”, the description can be like “Get the list of users registered in this portal.”

Section

This is a named item. If you can group several APIs under one section, you can keep this item. For example all the user related APIs are grouped under “Users” section. The value for this item should not be long. This will be like a title for several APIs.

This is an optional item. If this item is not present, the APIs will not be grouped and will be displayed in the index page.

Params

This is a named item. This should give information about all the accepted parameters and their acceptable values. The parameter name and value description should be present as sub-items. For example, the “Get users” api can have something like

"""
Params:
    max: Limits the amount of users returned
    type: Type of users, should be one of 'human', 'app' or 'system'
    another_param:
        This is a just a dummy parameter to demonstrate the usage 
        of multi line value.
"""

Output

This is a named item. This can occur multiple times, each time with the following sub-items names.

• status_code
• description

The situation in which the above status code is returned

• type

If the response with this status_code has any output data, the type of the data should be written here

• spec

A sample output and its description of the data if the above status code sends any output data.

For example

"""
Output:
    status_code: 200
    description:
        Queried the users successfully. Returns the list of the users.
        The fields of the each user dictionary varies the choice of the
        input parameters.
    type: application/json
    spec:
        [{
            "name": "Name of the user",
            "email_id": "Email id of the user",
            "id": "Internal identifier for the user",
            "type": "Some type"
        }, ...
        ]

Output:
    status_code: 400
    description: Some of the input parameters are not correct
"""

This item is optional.

Input

This is a named item. This can occur multiple time with each time having the following sub items.

• description

A simple description of the input data

• type

The content type of the input data.

• spec

A sample format of the input data with its description.

Example.

"""
Input:
    type: application/json
    description: User information in JSON format
    spec:
        {"name": "Name of the user"}

Input:
    type: application/xml
    description: User information in XML format
    spec:
        <user>
            <name>Name of the user</name>
        </user>
"""

Hook-Input

This is a named item. This is applicable only when the API accepts hooked data from the hookers. This item can occur multiple times, with each time having the same set of sub items for Input item.