api.json format

A schema is represented in JSON as a JSON object of the form:

    {
      "name": string,
      "apidoc": JSON Object of Apidoc (optional),
      "info": JSON Object of Info (optional),
      "namespace": string (optional),
      "base_url": string (optional),
      "description": string (optional),
      "imports": JSON Array of Import (optional),
      "headers": JSON Array of Header (optional),
      "enums": JSON Object of Enum (optional),
      "models": JSON Object of Model (optional),
      "unions": JSON Object of Union (optional),
      "resources": JSON Object of Resource (optional),
      "attributes": JSON Array of Attribute (optional)
    }
    
where:
  • name: the human readable name of this service. Used for display, and as the basis for generating a unique key for URL.
  • apidoc: optionally specify the specific version of apidoc for which your service is written. If not provided, we automatically default to the current production version. See Apidoc
  • info: optionally specify additional metadata about this service (e.g. contact info, license). See Info
  • namespace: specifies the namespace for this service. Namespace is primarily used when other services import definitions from your service and in the code generators when defining things like package names. If not specified, we will automatically generate a namespace based on [organization namespace].[formatted service name].[major version number]. Note that by default apidoc includes the major version number in the package name which allows service authors and clients to interact with multiple versions of the service where changes have been made in a non backwards compatible way.
  • baseUrl: the base URL where this service is hosted. Must start with http.
  • description optional description for what this service provides. Supports GFM.
  • imports JSON array defining any other services whose schema definitions we would like to import into our service.. See Import
  • headers JSON array defining any HTTP Headers that the service understands or expects. See Header
  • enums JSON object defining all of the enums in this API. The key of each object is the enum name. See Enum
  • models JSON object defining all of the models in this API. The key of each object is the model name. See Model
  • resources JSON object defining all of the resources in this API. The key of each object is the name of a type that this resource represents. The type must be the name of a model or an enum. See Resource
  • attributes JSON array defining additional meta data about this service. Attributes are used to add custom extensions to Apidoc and are typically used by generators to enable advanced code generation. See Attribute

Info declaration

The info node is represented as a JSON object of the form:

    {
      "contact": JSON Object of Contact (optional),
      "license": JSON Object of License (optional)
    }
    
where:
  • contact specifies contact information for this service. See Contact
  • license specifies the license under which this service is released. See License

Contact declaration

The contact node is represented as a JSON object of the form:

    {
      "name": string (optional),
      "url": string (optional),
      "email": string (optional)
    }
    
where:
  • name Identifying name of the contact person/organization
  • url URL pointing to the contact information
  • email Email address of the contact person/organization

License declaration

The license node is represented as a JSON object of the form:

    {
      "name": string,
      "url": string (optional)
    }
    
where:
  • name Name of the license - e.g. MIT
  • url URL of the license itself

Apidoc declaration

The apidoc node is represented as a JSON object of the form:

    {
      "version": string
    }
    
where:
  • version specifies the version of the apidoc specification that this file is written for. The latest version can be found by visiting /bryzek/apidoc-spec.

Model declaration

A model is represented as a JSON object of the form:

    {
      "name": {
        "description": string (optional),
        "plural": string (optional),
        "fields": JSON Array of Field,
        "attributes": JSON Array of Attribute (optional),
        "deprecation": JSON Object of Deprecation (optional)
      }
    }
    
where:
  • name specifies the name of the model. Names must be alphanumeric and start with a letter. Valid characters are a-z, A-Z, 0-9 and _ characters. The name must be unique in the set of names assigned to enums, models, or other union types.
  • plural specifies the optional, plural form of the name. By default, we will pluralize the name using a basic set of english heuristics. The plural is used as a default in cases where it is more natural to specify web services. For example, the default path for a resource will be the plural.
  • description optional description for what this model provides. Supports GFM.
  • fields indicates that one or more fields is required. See Field.
  • attributes JSON array defining additional meta data about this model for use by generators. See Attribute
  • deprecation JSON Object that indicates that this enum is deprecated.

Field declaration

A field is represented as a JSON object of the form:

    {
      "name": string,
      "type": string,
      "description": string (optional),
      "required": boolean (optional, true by default),
      "default": value (optional),
      "example": string (optional),
      "minimum": long (optional),
      "maximum": long (optional),
      "attributes": JSON Array of Attribute (optional),
      "deprecation": JSON Object of Deprecation (optional)
    }
    
where:
  • name specifies the name of the field. Names must be alphanumeric and start with a letter. Valid characters are a-z, A-Z, 0-9 and _ characters.
  • type specifies the type of this field. Acceptable values include the name of either an enum, a model, or a (primitive type). To specify a List, the type name can be wrapped with "[]". For example, to specify that the type is a collection of strings, use "[string]". To specify a Map, the type name can be prefixed with "map[type]". For example, to specify that the type is a Map of string to long, use "map[long]". Note that for map, the keys must be strings (per the JSON specification).
  • description optional description for what this field provides. Supports GFM.
  • required boolean: true|false. By default, all fields are considered required. To make a field optional, set "required" to false.
  • default optional default value. Can only be used for primitive types and enums. The value must be valid for the type specified for this field. For example, if you specify a field named 'limit' with type 'integer', an acceptable default would be 10
  • example optional - an example value for this field used only in the produced documentation
  • minimum optional - For a string, refers to the minimum length. For an array, the minimum number of elements in the array. For example, a value of 1 for an array would indicate the array must have at least 1 element.
  • maximum optional - For a string, refers to the maximum length. For an array, the maximum number of elements in the array. For example, a value of 1 for an array would indicate the array must have at most 1 element.
  • attributes JSON array defining additional meta data about this field for use by generators. See Attribute
  • deprecation JSON Object that indicates that this enum is deprecated.

Resource declaration

A resource is represented as a JSON object of the form:

    {
      "typeName": {
        "path": string (optional),
        "description": string (optional),
        "operations": JSON Array of Operation,
        "attributes": JSON Array of Attribute (optional),
        "deprecation": JSON Object of Deprecation (optional)
      }
    }
    
where
  • typeName the name of the model or enum that this resource represents
  • path optional path where this resource is located. If not provided, defaults to the plural of the typeName, with some assumptions of formatting for web (e.g. lower case, dash separated). Path parameters can be specified by prefixing a path element with ':'. For example, a path of '/:guid' would imply that all operations for this path will require a parameter named 'guid' of type 'string'
  • description optional description for what this resource provides. Supports GFM.
  • operations one or more operations is required. See Operation.
  • attributes JSON array defining additional meta data about this resource for use by generators. See Attribute
  • deprecation JSON Object that indicates that this enum is deprecated.

Operation declaration

An operation is represented as a JSON object of the form:

    {
      "method": string,
      "path": string (optional),
      "description": string (optional),
      "body": JSON Object of Body (optional),
      "parameters": JSON Array of Parameter (optional),
      "responses": JSON Object of Response (optional),
      "attributes": JSON Array of Attribute (optional),
      "deprecation": JSON Object of Deprecation (optional)
    }
    
where
  • method the HTTP method for this operation
  • path optional path for this particular operation. If not provided, defaults to no additional path. Path parameters can be specified by prefixing a path element with ':'. For example, a path of '/:guid' would imply that this operation is available at /resource_path/:guid. Path parameter types are inferred by looking for a field with that name on the model associated with this resource. If not found, the datatype of any path parameter will be string.
  • description optional description for what this operation provides. Supports GFM.
  • body optional specification for the type of the body of this request. For all operations that support bodies (e.g. POST, PUT, PATCH), allows you to specify the type of the body. See Body.
  • parameters optional JSON Array of the parameters to this method. By default, for GET and DELETE methods, parameters are assumed to be in the path or in the query. For other methods, parameters are assumed to be in the path or form body, unless you have explicitly specified a body in which case parameters can be provided in the path or the query. See Parameter.
  • responses optional JSON Object of HTTP Response Code to Response. If not provided, an HTTP NoContent response is assumed. Only responses for HTTP status codes that are interesting should be documented. See Response.
  • attributes JSON array defining additional meta data about this operation for use by generators. See Attribute
  • deprecation JSON Object that indicates that this enum is deprecated.

Body declaration

A body is represented as a JSON object of the form:

    {
      "type": string,
      "description": string (optional),
      "attributes": JSON Array of Attribute (optional),
      "deprecation": JSON Object of Deprecation (optional)
    }
    
where
  • type specifies the type of this body. Acceptable values include the name of either an enum, a model, or a (primitive type). To specify a List, the type name can be wrapped with "[]". For example, to specify that the type is a collection of strings, use "[string]". To specify a Map, the type name can be prefixed with "map[type]". For example, to specify that the type is a Map of string to long, use "map[long]". Note that for map, the keys must be strings (per the JSON specification).
  • description optional description for what this body provides. Supports GFM.
  • attributes JSON array defining additional meta data about this body for use by generators. See Attribute
  • deprecation JSON Object that indicates that this enum is deprecated.

Parameter declaration

A parameter is represented as a JSON object of the form:

    {
      "name": string,
      "type": string,
      "location": string (optional),
      "description": string (optional),
      "deprecation": JSON Object of Deprecation (optional),
      "required": boolean (optional, true by default),
      "default": value (optional),
      "example": string (optional),
      "minimum": long (optional),
      "maximum": long (optional)
    }
    
where
  • name the name of the parameter. Names must be alphanumeric and must start with a letter. Valid characters are a-z, A-Z, 0-9 and _ characters.
  • type specifies the type of this parameter. Acceptable values include the name of either an enum, a model, or a (primitive type). To specify a List, the type name can be wrapped with "[]". For example, to specify that the type is a collection of strings, use "[string]". To specify a Map, the type name can be prefixed with "map[type]". For example, to specify that the type is a Map of string to long, use "map[long]". Note that for map, the keys must be strings (per the JSON specification).
  • location one of: path, query, form, header. Defines the location of this parameter. Default location varies based on the context of the parameter (e.g. if the operation method is a POST, the default will be Form; if a GET, the default will be Query)
  • description optional description for what this parameter provides. Supports GFM.
  • required boolean: true|false. By default all parameters are considered required. To make a parameter optional, set "required" to false.
  • default optional default value. Can only be used for primitive and enum types. The value must be valid for the type specified for this parameter. For example, if you specify a parameter named 'limit' with type 'integer', an acceptable default would be 10
  • example optional - an example value for this parameter used only in the produced documentation
  • minimum optional - For a string, refers to the minimum length. For an array, the minimum number of elements in the array. For example, a value of 1 for an array would indicate the array must have at least 1 element.
  • maximum optional - For a string, refers to the maximum length. For an array, the maximum number of elements in the array. For example, a value of 1 for an array would indicate the array must have at most 1 element.
  • deprecation JSON Object that indicates that this enum is deprecated.

Enum declaration

An enum is represented as a JSON object of the form:

    {
      "name": string,
      "plural": string (optional),
      "description": string (optional),
      "values": JSON Array of EnumValue,
      "attributes": JSON Array of Attribute (optional),
      "deprecation": JSON Object of Deprecation (optional)
    }
    
where
  • name the name of the enum. Names must be alphanumeric and must start with a letter. Valid characters are a-z, A-Z, 0-9 and _ characters. The name must be unique in the set of names assigned to enums, models, or other union types.
  • plural specifies the optional, plural form of the name. By default, we will pluralize the name using a basic set of english heuristics. The plural is used as a default in cases where it is more natural to specify web services. For example, the default path for a resource will be the plural.
  • description optional longer description for this enum.
  • values Json Array of EnumValue objects. Each element defines a valid value and an optional description. See EnumValue.
  • attributes JSON array defining additional meta data about this enum for use by generators. See Attribute
  • deprecation JSON Object that indicates that this enum is deprecated.

EnumValue declaration

An EnumValue is represented as a JSON object of the form:

    {
      "name": string,
      "description": string (optional),
      "attributes": JSON Array of Attribute (optional),
      "deprecation": JSON Object of Deprecation (optional)
    }
    
where
  • name the name of the value. Names must start with a letter.
  • description optional description for what this enum value provides. Supports GFM.
  • attributes JSON array defining additional meta data about this enum value for use by generators. See Attribute
  • deprecation JSON Object that indicates that this enum is deprecated.

Union declaration

    {
      "name": {
        "plural": string (optional),
        "discriminator": string (optional),
        "description": string (optional),
        "types": JSON Array of UnionType,
        "attributes": JSON Array of Attribute (optional),
        "deprecation": JSON Object of Deprecation (optional)
      }
    }
    
where:
  • name specifies the name of the union type. Names must be alphanumeric and start with a letter. Valid characters are a-z, A-Z, 0-9 and _ characters. The name must be unique in the set of names assigned to enums, models, or other union types.
  • plural specifies the optional, plural form of the name. By default, we will pluralize the name using a basic set of english heuristics. The plural is used as a default in cases where it is more natural to specify web services. For example, the default path for a resource will be the plural.
  • discriminator specifies an optional, but recommended, name for a type discriminator field which can then be used in serialization / deserialization to identify the type of object. For example, if not specified, a code generator may serialize the union type into a JSON structure of { "type" => object }. If a discriminator is provided, the same code generator can flatten the JSON representation to, for example: { "discriminator" => "xxx", "field1" => "yyy" }. If provided, the name of the discriminator field must be unique across all of the fields across all of the types of this union. See Play Union Types for more information and examples.
  • description optional description for what this union provides. Supports GFM.
  • types Specifies the individual types that are part of this union type. See UnionType.
  • attributes JSON array defining additional meta data about this union for use by generators. See Attribute
  • deprecation JSON Object that indicates that this enum is deprecated.

UnionType declaration

A UnionType is represented as a JSON object of the form:

    {
      "type": string,
      "description": string (optional),
      "attributes": JSON Array of Attribute (optional),
      "deprecation": JSON Object of Deprecation (optional)
    }
    
where
  • type specifies the type to include in this union type. Acceptable values include the name of either an enum, a model, or a (primitive type).
  • description optional description for what this type provides. Supports GFM.
  • attributes JSON array defining additional meta data about this union type for use by generators. See Attribute
  • deprecation JSON Object that indicates that this enum is deprecated.

Import declaration

An import is represented as a JSON object of the form:

    {
      "uri": string
    }
    
where

Header declaration

An header is represented as a JSON object of the form:

    {
      "name": string,
      "type": string,
      "required": boolean (optional, true by default),
      "default": value (optional),
      "description": string (optional),
      "attributes": JSON Array of Attribute (optional),
      "deprecation": JSON Object of Deprecation (optional)
    }
    
where
  • name the name of the header.
  • type the type of this header. Acceptable values are either the name of an enum or string. To specify a collection (meaning multiple values for this header can be provided), the type name can be wrapped with "[]". For example, to specify that the type is a collection of strings, use "[string]".
  • required boolean: true|false. By default, all headers are considered required. To make a parameter optional, set "required" to false.
  • default the default value for this header. If specified, generated clients will automatically include this header in all requests. Default values must be specified as strings.
  • description optional description for what this header provides. Supports GFM.
  • attributes JSON array defining additional meta data about this header for use by generators. See Attribute
  • deprecation JSON Object that indicates that this enum is deprecated.

Response declaration

A response is represented as a JSON object of the form:

    {
      "http_status_code": {
        "type": type,
        "headers": JSON Array of Header (optional),
        "description": string (optional),
        "deprecation": JSON Object of Deprecation (optional)
      }
    }
    
where
  • http_status_code A valid HTTP status code for this response (e.g. 200). Only status codes that have interesting return types should be documented. You can also specify an HTTP status code of 'default' to map to all other non documented types. This is useful to capture a generic error type that would be returned for non documented response codes.
  • type specifies the type of this response. Acceptable values include the name of either an enum, a model, or a (primitive type). To specify a List, the type name can be wrapped with "[]". For example, to specify that the type is a collection of strings, use "[string]". To specify a Map, the type name can be prefixed with "map[type]". For example, to specify that the type is a Map of string to long, use "map[long]". Note that for map, the keys must be strings (per the JSON specification).
  • description optional description for what this response provides. Supports GFM.
  • deprecation JSON Object that indicates that this enum is deprecated.
There are a few conventions enforced:
  • HTTP Response codes of 5xx cannot be explicitly specified and are handled automatically to ensure consistent behavior in generated client libraries.
  • HTTP Response codes of 204 and 304 indicate that no content is returned, so they must use a type of unit.

Attribute declaration

An attribute is represented as a JSON object in the following form:

    {
      "name": string,
      "value": JSON Object
    }
    
where
  • name the name and identifier of the attribute.
  • value a JSON object that is usually utilized by a downstream Generator.
Example attribute:
    {
      "name": "my_regex_validation",
      "value": {
        "regex": "[a-z]"
      }
    }
    

Deprecation declaration

A deprecation is represented as a JSON object of the form:

    {
      "description": string (optional)
    }
    
where
  • description optional, but recommended to contain notes for what the user is supposed to do now that this property is deprecated. Supports GFM.