Support for

API reference: documentation style

John Valentine
by John Valentine 9 years ago
 

Conventions

Our conventions for formatting our API documentation can have the following elements:

  • Title: what an API call does.
  • Path: the HTTP URL's location, including ids.
  • Description: a bit more detail.
  • Parameters: a table of parameters, their value spec and effects.
  • Request example.
  • Response example.
  • Response Items: a table of possible items found in the response.
  • Relations: how data is shared between objects and methods.

Appearance

Code or data files are boxes and labelled with their type, e.g.

HTTP request
GET http://api.templatecloud.com/sandbox/tag_types/?user_key=ba386e729c5f6870cea89f38e92d7a5c&format=json
HTTP response (JSON)
{
    "tag_types": [
        {
            "id": "1",
            "name": "Industry Types"
        },
        {
            "id": "2",
            "name": "Client"
        },
        etc...
    ]
}

Aside from standard code highlighting, we style as follows:

  • keywords or reserved words
    also used to identify nouns in the API path.
  • literal strings
    identify values for variables, or literally-entered text.
  • variables
    identify a variable or parameter name.
  • arguments
    identify a place where an argument should be inserted.
  • comments
  • annotations (comments set apart from the code)
 

Jump to contents page of

TemplateCloud API Guide

Flyerlink API Guide

 
 
 

All content is (c) Nettl Systems Limited, 2024 and may not be used, copied or distributed without permission.