# 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](https://www.python.org/dev/peps/pep-0257/) 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: Name of the 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.