api.json format

Define your complete API in a single JSON file. The api.json format is API Builder's native specification — simple enough for a novice, expressive enough for production APIs.

Quick Reference

◆ Core Structure

Top-level Schema

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 https://app.apibuilder.io/apicollective/apibuilder-spec/latest.

T Types

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.

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 a 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.

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.

Union declaration

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

{
  "name": {
    "plural": string (optional),
    "fields": JSON Array of Field (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 union. 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.
fields: Optional JSON Array of 0 or more Fields. If specified, API Builder will create a model named after the type with these specified fields. This is syntactic sugar for creating the model yourself and then referencing here as the type.
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 discriminator 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.

⚡ API

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 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 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.

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.

⚙ Metadata

Import declaration

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

{
  "uri": string
}

where:

uri: The complete URI to the service specification that we are importing. Within API Builder, you can find the URL to the service specification by clicking on the "service.json" link for a service. Example: https://app.apibuilder.io/apicollective/apibuilder-api/0.16.53/service.json.

Header declaration

A 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.

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]"
  }
}

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 annotation.
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.

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.

Templates declaration

Templates are an experimental feature to create reusable definitions of the various features in API Builder. See Templates for more information.

"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.

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"
  }
} ]

Ready to build your first API?

Get Started