api.json format
A schema is represented in JSON as a JSON object of type api json:
{
"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),
"interfaces": JSON Object of Interface (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),
"annotations": JSON Object of Annotation (optional),
"templates": JSON Object of Templates (optional and experimental),
}
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 API Builder 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 API Builder 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 API Builder and are typically used by generators to enable advanced code generation. See Attribute
- annotations JSON array defining annotations or tags that can be applied to fields regardless of their type. Annotations are intended to convey usage hints to consumers of the API. See Annotations
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 API Builder specification that this file is written for. The latest version can be found by visiting /apicollective/apibuilder-spec.
Interface declaration
An interface is represented as a JSON object of the form:
{
"name": {
"description": string (optional),
"plural": string (optional),
"fields": JSON Array of Field (optional),
"attributes": JSON Array of Attribute (optional),
"deprecation": JSON Object of Deprecation (optional)
}
}
where:
- name specifies the name of the interface. 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, interfaces, or models. Note you may define an interface and a union of the same name.
- 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 JSON Array of 0 or more Fields.
- attributes JSON array defining additional meta data about this model for use by generators. See Attribute
- deprecation JSON Object that indicates that this object is deprecated.
More information about interfaces can be found
here.
Model declaration
A model is represented as a JSON object of the form:
{
"name": {
"description": string (optional),
"plural": string (optional),
"interfaces": JSON Array of type string where each value indicates the name of a declared interface (optional),
"fields": JSON Array of Field,
"templates": JSON Array of Template Declaration (optional),
"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, interfaces, models, or unions 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 object 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),
"annotations": JSON Array of type string where each value indicates the name of a declared annotation (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. 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 object is deprecated.
When a field is marked as required, it must be present in any form of a model for that form to be valid. In client-server scenario, this means that any defaults that are present in the model must be applied by the client. If you want a default to be applied by the receiver, you should mark the field as
"required": false
.
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,
"templates": JSON Array of Template Declaration (optional),
"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 object 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 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 object 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 object 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),
"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 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. 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.
- attributes JSON array defining additional meta data about this parameter for use by generators. See Attribute
- deprecation JSON Object that indicates that this object is deprecated.
Enum declaration
An enum is represented as a JSON object of the form:
{
"name": {
"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, interfaces, models, or unions 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 object is deprecated.
EnumValue declaration
An EnumValue is represented as a JSON object of the form:
{
"name": string,
"value": string (optional),
"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.
- value the actual string representation of this value when serializing. If not specified, defaults to 'name'.
- 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 object is deprecated.
Union declaration
{
"name": {
"plural": string (optional),
"discriminator": string (optional),
"description": string (optional),
"interfaces": JSON Array of type string where each value indicates the name of a declared interface (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 interface. 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, unions, or models. Note you may define an interface and a union of the same name, but in this case it is required to list that interface in the interfaces field.
- 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 object is deprecated.
UnionType declaration
A UnionType is represented as a JSON object of the form:
{
"type": string,
"description": string (optional),
"default": boolean (optional),
"discriminator_value": 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.
- default If true, indicates that this type should be used as the default when deserializing union types. This field is only used by union types that require a discriminator and sets the default value for that disciminator during deserialization.
- discriminator_value The discriminator value defines the string to use in the discriminator field to identify this type. If not specified, the discriminator value will default to the name of the type itself.
- attributes JSON array defining additional meta data about this union type for use by generators. See Attribute
- deprecation JSON Object that indicates that this object 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 object 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),
"attributes": JSON Array of Attribute (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.
- attributes JSON array defining additional meta data about this service. Attributes are used to add custom extensions to API Builder and are typically used by generators to enable advanced code generation. See Attribute
- deprecation JSON Object that indicates that this object 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.
Template declaration
A template declaration is represented as a JSON object in the following form:
{
"name": string,
"cast": JSON Object of strings (optional)
}
where
- name the name of the template.
- cast a JSON object used to map types in the template to concrete types to use for this resource.
Example template declaration:
"templates": [ {
"name": "currency_setting",
"cast": {
"currency_setting": "organization_currency_setting",
"currency_setting_form": "organization_currency_setting_form"
}
} ],
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.
Annotation declaration
An annotation is just a short key that can be used to tag any field in any model of this API. The
intent is to convey additional information about how a field might be used that isn't apparent
in either the field's type or API semantics. For example, if you wanted to clearly identify
fields of an API that may contain private customer data, you would create a privacy
annotation and add "annotations": ["privacy"] to all such fields.
Generated code may preserve annotations either in the type system, documentation or via metaprogramming
facilities depending on language support. Generated documentation should include the tag when displaying
a field, along with a link to the annotation's declaration.
"annotations": {
"personal_data": {
"description": "Identifies a field that contains Personal Data, as defined by GDPR.",
"deprecation": JSON Object of Deprecation (optional)
}
}
where
- name the name of the header.
- description optional, but recommended to explain how
you intend the tag to clarify the usage of a field,
possibly including links to additional documentation
- deprecation JSON Object that indicates that this object is deprecated.
Templates declaration
Templates are an experimental feature to create reusable definitions of
the various features in API Builder. See Templates
for more information.
Generated code may preserve annotations either in the type system, documentation or via metaprogramming
facilities depending on language support. Generated documentation should include the tag when displaying
a field, along with a link to the annotation's declaration.
"templates": {
"models": JSON Object of Model (optional),
"resources": JSON Object of Resource (optional),
}
where
- models JSON object defining templates for models in this API. The key of each object is the model template name. See Model
- resources JSON object defining templates for resources in this API. The key of each object is the name of a template resource type.