Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

perfectapi config file format

DukeyToo edited this page · 9 revisions

File format is JSON. An example config is at the bottom of this page.

Top level elements

  • exports - name of the api. Used in clients to call api, e.g. "exports": "amigen" will expose a Javascript object amigen with methods to call the API, or a C# class Amigen.
  • path - the path of the API when hosted on a server. e.g. if "path": "apis/amigen/v1" then the server endpoint will be at that location.
  • environment - parameters that can be read from the OS environment. This section should also be used for security credentials and tokens, i.e. things that you do not want exposed in the querystring.
  • signature - describes the API itself. Is an array of one or more commands.

Signature section

This section is the core of the API. An API is made up of 1 or more commands, each of which is described in detail. The signature section is an array of those commands. Each command has the following attributes:

  • name - the name of the command. Used throughout to refer to the command
  • synopsis - short one-line description for the command. Used when displaying brief help to the user.
  • description - more detailed description for the command.
  • verb - when accessed via a service, the recommended HTTP method to use to access this command. Either GET or POST.
  • maxage - optional integer value in seconds. When specified, caching will automatically occur. Only valid if the verb is GET. Use when the data returned by this command is static, or when it does not matter if the client has outdated data.
  • parameter - describes a parameter to the command when the command only has one parameter.
    • name - name of the parameter
    • required - when true, indicates that the parameter is required
    • type - currently only supports multi (indicating an array of parameters) or single (default).
  • parameters - an array of parameter. Use instead of parameter when the command has more than one parameter.
  • options - describes the options for the command. There are two types of option, namely option (an option that takes a value) and flag (a special type of option that is either true or false - its existence implies true).
    • option - the name of an option.
    • flag - the name of a flag.
    • long - DEPRECATED. Name of the option when specified via command-line --long format.
    • short - single character for the option when specified via command-line short -s format.
    • default - a default value for the option. Not used for flags (all flags default false).
    • description - a short one-line description of the option
    • required - when true, the option is required (otherwise it is optional).
  • returns - describes what the api returns. At time of this writing this is ignored.

Environment section

The environment section has 2 purposes. Most obviously, it is a section that defines environment variables that your API can utilize. These variables are automatically read from the OS (when possible). So for example, if you run your API as a service, and the environment variables are accessible to that service, then the variables will be defaulted.

The less obvious purpose is for security credentials and tokens. Placing those in this section has several benefits:

  • they can be read from the environment if they are available
  • two different implementations of an API can differ only in their environment, and still be considered functionally compatible. For example, I might have two APIs that read and write to cloud storage. One has an environment that accepts 2 AWS secret keys, and another accepts a single Rackspace secret key. Both APIs can share the same signature and can therefor be used interchangeably.

The environment section is an array of parameters, each of which has the following attributes:

  • parameter - name of the environment variable. Must match the name in the OS.
  • long - DEPRECATED. Name of the option when specified via command-line --long format.
  • short - single character for the option when specified via command-line short -s format.
  • required - defaults to false. When true, indicates that this parameter is required for correct functioning of the API
  • allowOverride - defaults to false. When true, a server running this API will allow the client to override the variable. This can be a security risk, which is why it defaults to false. CLI interface ignores this parameter.

Example file

{   "exports": "amigen",
    "signature": [
        { 
            "name": "gen",
            "synopsis": "Generates a new Amazon EC2 image using the supplied scripts",
            "description": "Using a baseAMI and a set of scripts, builds up (or finds existing) AMI image that matches the criteria",
            "verb": "POST",
            "parameter": {"name": "scripts", "required":"true", "type":"multi"},
            "options": 
                [{"option": "root", "short":"r", "required":"false", "default":"scripts", "description":"specify the root folder where scripts can be found"},
                 {"option": "ami", "required":"false", "short":"a", "description":"the AMI name that will form the basis of the new images"},
                 {"option": "region", "default":"us-east-1", "short":"e", "description":"The amazon region in which to create the image"},
                 {"flag": "bit32", "default":"false", "short":"3", "description":"if set, the resulting AMI will be a 32 bit image.  Ignored if a specific base AMI is specified (--ami)."},
                 {"flag": "bit64", "default":"true", "short":"6", "description":"if set, the resulting AMI will be a 64 bit image.  Ignored if a specific base AMI is specified (--ami)."},
                 {"flag": "publish", "short":"p", "default":"false", "description":"if set, the resulting AMI(s) will be made public"}],
            "returns": 
                [{"name":"ami", "description":"Amazon AMI Image Id, e.g. ami-bf62a9d6"},
                 {"name":"region", "description":"Amazon AWS region in which the ami can be found"}
                ]
        },
        {
            "name": "scripts",
            "synopsis": "Lists available scripts for use in gen",
            "description": "Finds the available scripts, which are stored in subfolders of the root (see root option)",
            "verb": "GET",
            "maxage": 720,
            "options": 
                [{"option": "root", "required":"false", "default":"scripts", "short":"r"}],
            "returns": 
                [{"name":"scripts", "type":"list", "description":"List of scripts relative to the root path"} ]
        },
        {
            "name": "regions",
            "synopsis": "Lists available Amazon regions",
            "description": "Lists the available regions",
            "verb": "GET",
            "maxage": 172800,
            "returns": 
                [{"name":"regions", "type":"list", "description":"List of amazon regions"} ]
        }
    ], 
    "path": "apis",
    "environment": [
        {"parameter": "AWS_ACCESS_KEY_ID", "short":"k", "required":"true"},
        {"parameter": "AWS_SECRET_ACCESS_KEY", "short":"s", "required":"true"}
    ]
}
Something went wrong with that request. Please try again.