apibuilder spec 0.15.70 - API Collective

Specification of apibuilder api.json schema

Contact: Michael Bryzek mbryzek@alum.mit.edu http://twitter.com/mbryzek

License: MIT

Version:

annotation

Example JSON: |

Used to indicate an API concern for a field that is specific to the field's usage but not necessarily its data type. For example, you might use annotations to mark that certain fields contain PII or PCI data and thus should not be stored once processing is complete. Annotations communicate meaning to consumers of an API and may also be used within an implementation or tooling; for example, using static analysis tools to detect logging of sensitive data.

Field	Type
name required	string
description	string
deprecation	deprecation

apidoc

Example JSON: |

Field	Type	Description
version required	string	e.g. 1.0.3

application

Example JSON: |

Field	Type	Description
key required	string	Unique key identifying this application

attribute

Example JSON: |

Represents an additional attribute that is attached to one of the objects in apibuilder. The main use case is to capture additional metadata that doesn't necessarily define the API but aids in code generation. Examples would be hints for certain code generators about classes to extend, interfaces to implement, annotations to add, names to assign to certain methods, etc. The specific attributes will be applicable only in the context of the specific code generators usings them.

Field	Type
name required	string
value required	object
description	string
deprecation	deprecation

body

Example JSON: |

Field	Type	Description
type required	string
description	string
deprecation	deprecation
attributes required	[attribute]	default: []

contact

Example JSON: |

Describes the primary contact for this service

Field	Type	Description
name	string	e.g. Michael Bryzek
url	string	e.g. https://www.apibuilder.io
email	string	e.g. michael@test.apibuilder.io

deprecation

Example JSON: |

Indicates that this particular element is considered deprecated in the API. See the description for details

Field	Type
description	string

enum

Example JSON: |

Field	Type	Description
name required	string
plural required	string
description	string
deprecation	deprecation
values required	[enum_value]
attributes required	[attribute]	default: []

enum_value

Example JSON: |

Field	Type	Description
name required	string
description	string
deprecation	deprecation
attributes required	[attribute]	default: []
value	string	The actual string representation of this value. If not specified, defaults to 'name'

field

Example JSON: |

Field	Type	Description
name required	string
type required	string
description	string
deprecation	deprecation
default	string
required required	boolean
minimum	long
maximum	long
example	string
attributes required	[attribute]	default: []
annotations required	[string]	default: []

header

Example JSON: |

Field	Type	Description
name required	string
type required	string
description	string
deprecation	deprecation
required required	boolean
default	string
attributes required	[attribute]	default: []

import

Example JSON: |

An import is used to declare a dependency on another application. This allows you to reference the models and or enums from that application in your own app.

Field	Type	Description
uri required	string	Full URI to the service.json file of the service we are importing e.g. https://www.apibuilder.io/apicollective/apibuilder-spec/0.7.38/service.json
namespace required	string	the fully qualified namespace that we have imported e.g. io.apibuilder
organization required	organization
application required	application
version required	string	The version of the service that we are importing e.g. 1.0.0
enums required	[string]	default: [] Enums made available by this import
interfaces required	[string]	default: [] Interfaces made available by this import
unions required	[string]	default: [] Unions made available by this import
models required	[string]	default: [] Models made available by this import
annotations required	[annotation]	default: [] Annotations made available by this import

info

Example JSON: |

General metadata about this service

Field	Type
license	license
contact	contact

interface

Example JSON: |

Field	Type	Description
name required	string
plural required	string
description	string
deprecation	deprecation
fields required	[field]
attributes required	[attribute]	default: []

license

Example JSON: |

Describes the software license contact for this service

Field	Type	Description
name required	string	e.g. MIT
url	string	e.g. http://opensource.org/licenses/MIT

model

Example JSON: |

Field	Type	Description
name required	string
plural required	string
description	string
deprecation	deprecation
fields required	[field]
attributes required	[attribute]	default: []
interfaces required	[string]	default: []

operation

Example JSON: |

Field	Type	Description
method required	method
path required	string	The full path to this operation, relative to the service's base url.
description	string
deprecation	deprecation
body	body
parameters required	[parameter]	default: []
responses required	[response]	default: []
attributes required	[attribute]	default: []

organization

Example JSON: |

Field	Type	Description
key required	string	Unique key identifying the organization that owns this service

parameter

Example JSON: |

Field	Type
name required	string
type required	string
location required	parameter_location
description	string
deprecation	deprecation
required required	boolean
default	string
minimum	long
maximum	long
example	string
attributes	[attribute]

resource

Example JSON: |

Field	Type	Description
type required	string	The type of this resource will map to a defined model, enum, or union type
plural required	string
path	string	The path to this specific resource. This was added in 2016 to help us differentiate between the resource path and the operation path which can be helpful when, for example, generating method names for operations. This field is optional as some of our input formats (e.g. swagger) do not explicitly differentiate resoure paths.
description	string
deprecation	deprecation
operations required	[operation]
attributes required	[attribute]	default: []

response

Example JSON: |

Field	Type
code required	response_code
type required	string
headers	[header]
description	string
deprecation	deprecation
attributes	[attribute]

service

Example JSON: |

Field	Type	Description
apidoc required	apidoc	Documents that this is an apibuilder document, noting the specific version used. Internally the version is then used for backwards compatibility when applicable as new features are added to apibuilder. Note naming refers to the original name of this project, 'apidoc', and is left here to avoid a breaking change for preexisting services.
name required	string
organization required	organization
application required	application
namespace required	string	Fully qualified namespace for this service e.g. io.apibuilder
version required	string	e.g. 1.0.0
base_url	string
description	string
info required	info
headers required	[header]	default: []
imports required	[import]	default: []
enums required	[enum]	default: []
interfaces required	[interface]	default: []
unions required	[union]	default: []
models required	[model]	default: []
resources required	[resource]	default: []
attributes required	[attribute]	default: []
annotations required	[annotation]	default: []

union

Example JSON: |

Field	Type	Description
name required	string
plural required	string
discriminator	string	If a type discriminator is provided, serialization of these union types will always contain a field named with the value of the discriminator that will contain the name of the type. This provides a simpler (for many use cases) JSON serialization/deserialization mechanism. When specified, apibuilder itself will verify that none of the types in the union type itself contain a field with the same name as the discriminator e.g. discriminator or type
description	string
deprecation	deprecation
types required	[union_type]	min: 1 The names of the types that make up this union type
attributes required	[attribute]	default: []
interfaces required	[string]	default: []

union_type

Example JSON: |

Metadata about one of the types that is part of a union type

Field	Type	Description
type required	string	The name of a type (a primitive, model name, or enum name) that makes up this union type
description	string
deprecation	deprecation
attributes required	[attribute]	default: []
default	boolean	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	string	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.