Resources Enums Interfaces Models Unions Clients

apibuilder api 0.16.53

History | Watch

Host API documentation for applications providing REST APIs, facilitating the design of good resource first APIs.

Resources

application

Operations

Method and Path Description
GET /:orgKey/metadata/:applicationKey/versions

Returns the versions assocoated with the specified application. The latest version is the first result returned.
GET /:orgKey/metadata/:applicationKey/versions/latest.txt

Returns the latest version number as a string
GET /:orgKey

Search all applications. Results are always paginated.
POST /:orgKey

Create an application.
PUT /:orgKey/:applicationKey

Updates an application.
DELETE /:orgKey/:applicationKey

Deletes a specific application and its associated versions.
POST /:orgKey/:applicationKey/move

Moves application to a new organization.

attribute

Operations

Method and Path Description
GET /attributes

Search all attributes. Results are always paginated.
GET /attributes/:name

Returns the attribute with this name.
POST /attributes

Create a new attribute.
DELETE /attributes/:name

Deletes the attribute with this name. Only the user who created an attribute can delete it.

authentication

Operations

Method and Path Description
GET /authentications/session/:id

batch_download_applications

Operations

Method and Path Description
POST /:orgKey/batch/download/applications

Retrieve multiple applications in one api call.

change

Operations

Method and Path Description
GET /changes

code

Operations

Method and Path Description
POST /:orgKey/:applicationKey/:version/form

Create an invocation form. This is useful primarily for debugging when you want to see exactly what content is being forwarded to the generator
GET /:orgKey/:applicationKey/:version/:generatorKey

Generate code for a specific version of an application.
POST /:orgKey/:applicationKey/:version/:generatorKey

Generate code for a specific version of an application.

domain

Operations

Method and Path Description
POST /domains/:orgKey

Add a domain to this organization
DELETE /domains/:orgKey/:name

Remove this domain from this organization

email_verification_confirmation_form

Operations

Method and Path Description
POST /email_verification_confirmations

Validate an email address using a token.

generator_service

Operations

Method and Path Description
GET /generator_services

List all generator services
GET /generator_services/:guid
POST /generator_services
DELETE /generator_services/:guid

Deletes a generator service.

generator_with_service

Operations

Method and Path Description
GET /generators

List all available generators
GET /generators/:key

io.apibuilder.generator.v0.models.healthcheck

Operations

Method and Path Description
GET /_internal_/healthcheck

item

Operations

Method and Path Description
GET /items
GET /items/:guid

membership

Operations

Method and Path Description
GET /memberships

Search all memberships. Results are always paginated.
GET /memberships/:guid
DELETE /memberships/:guid

membership_request

Operations

Method and Path Description
GET /membership_requests

Search all membership requests. Results are always paginated.
POST /membership_requests

Create a membership request
POST /membership_requests/:guid/accept

Accepts this membership request. User will become a member of the specified organization.
POST /membership_requests/:guid/decline

Declines this membership request. User will NOT become a member of the specified organization.

organization

Operations

Method and Path Description
GET /organizations

Search all organizations. Results are always paginated.
GET /organizations/:key

Returns the organization with this key.
POST /organizations

Create a new organization.
PUT /organizations/:key

Update an organization.
DELETE /organizations/:key

Deletes an organization and all of its associated applications.
GET /organizations/:key/attributes

Returns all attribute values for this organization. Results are always paginated.
GET /organizations/:key/attributes/:name

Returns the attribute value with this name.
PUT /organizations/:key/attributes/:name

Create or update a new attribute value.
DELETE /organizations/:key/attributes/:name

Deletes the attribute value with the specified name. Only the user who created an attribute value can delete it.

password_reset

Operations

Method and Path Description
POST /password_resets

Change the password for this token. If the token is invalid, has been used, or otherwise no longer can be applied, errors will be returned as 409s. A 204 represents that the user has successfully changed their password.

password_reset_request

Operations

Method and Path Description
POST /password_reset_requests

Create a new password reset. This will send the user an email with a link to reset their password.

subscription

Operations

Method and Path Description
GET /subscriptions

Search subscriptions. Always paginated.
GET /subscriptions/:guid

Returns information about a specific subscription.
POST /subscriptions

Create a new subscription.
DELETE /subscriptions/:guid

token

Operations

Method and Path Description
GET /tokens/users/:user_guid
GET /tokens/:guid/cleartext

Used to fetch the clear text token.
POST /tokens

Create a new API token for this user
DELETE /tokens/:guid

user

Operations

Method and Path Description
GET /users

Search for a specific user. You must specify at least 1 parameter - either a guid, email or token - and will receive back either 0 or 1 users.
GET /users/:guid

Returns information about the user with this guid.
POST /users/authenticate

Used to authenticate a user with an email address and password. Successful authentication returns an instance of the user model. Failed authorizations of any kind are returned as a generic error with code user_authorization_failed.
POST /users/authenticate_github

Used to authenticate a user using a github access token. This is equivalent to running the following command to get the user info: curl -H 'Authorization: Bearer code' https://api.github.com/user
POST /users

Create a new user.
PUT /users/:guid

Updates information about the user with the specified guid.

validation

Public resource that can accept JSON input and returns a validation object describing any validation errors.

Operations

Method and Path Description
POST /validations

version

Operations

Method and Path Description
GET /:orgKey/:applicationKey

Search all versions of this application. Results are always paginated.
GET /:orgKey/:applicationKey/:version

Retrieve a specific version of an application.
POST /:orgKey/:version

Create a new version for an application
PUT /:orgKey/:applicationKey/:version

Upsert a version of an application
DELETE /:orgKey/:applicationKey/:version

Deletes a specific version.
GET /:orgKey/:applicationKey/:version/example/:type_name

Generates an example JSON document of the type with the specified name.

watch

Operations

Method and Path Description
GET /watches

Search attributes. Always paginated.
GET /watches/:guid

Returns information about a specific watch.
GET /watches/check

Quick check if a user is watching a specific application.
POST /watches

Create a new watch.
DELETE /watches/:guid

Headers

No headers

Imports

https://app.apibuilder.io/apicollective/apibuilder-common/latest/service.json
https://app.apibuilder.io/apicollective/apibuilder-generator/latest/service.json
https://app.apibuilder.io/apicollective/apibuilder-spec/latest/service.json

Enums

app_sort_by

Name Value Description
name name

created_at created_at

updated_at updated_at

visibility visibility

original_type

Name Value Description
api_json api_json

The original is in the api.json format
avro_idl avro_idl

The original is in Avro Idl format
service_json service_json

This is the canonical service spec for apibuilder itself. See https://www.apibuilder.io/apicollective/apibuilder-spec/latest#model-service
swagger swagger

The original in the Swagger JSON or YAML format

publication

A publication represents something that a user can subscribe to. An example would be subscribing to an email alert whenever a new version of an application is created.

Name Value Description
membership_requests.create membership_requests.create

For organizations for which I am an administrator, email me whenever a user applies to join the org.
memberships.create memberships.create

For organizations for which I am a member, email me whenever a user joins the org.
applications.create applications.create

For organizations for which I am a member, email me whenever an application is created.
versions.create versions.create

For applications that I watch, email me whenever a version is created.
versions.material_change versions.material_change

For applications that I watch, email me whenever there is a material change. Generally, this means avoiding email for simple changes (like only a version change).

sort_order

Name Value Description
asc asc

desc desc

visibility

Controls who is able to view this version

Name Value Description
user user

Only the creator can view this application
organization organization

Any member of the organization can view this application
public public

Anybody, including non logged in users, can view this application

Interfaces

diff

Represents a single breaking diff of an application version. A breaking diff indicates that it is possible for an existing client to now experience an error or invalid data due to the diff.

Field Type Required? Default Description
description string Yes -

Example: model removed: user
is_material boolean Yes -

Example: True if this is a material change (eg something important). False otherwise. This is used to drive the publication 'versions.material_change'

Models

application

Example Json: Minimal | Full

Interfaces: None

An application has a name and multiple versions of its API.

Field Type Required? Default Description
guid uuid Yes -

Internal unique identifier for this application.
organization io.apibuilder.common.v0.models.reference:0.16.53 Yes -

name string Yes -

The unique name for this application.
key string Yes -

Used as a unique key in the URL path. Key is automatically derived from the application name.
visibility visibility Yes -

Controls who is able to view this application
description string No -

last_updated_at date-time-iso8601 Yes -

The updated_at of this application or created_at of it's latest version
audit io.apibuilder.common.v0.models.audit:0.16.53 Yes -

application_form

Example Json: Minimal | Full

Interfaces: None

Field Type Required? Default Description
name string Yes -

key string No -

Defaults to a key generated from the application name
description string No -

visibility visibility Yes -

application_metadata

Example Json: Minimal | Full

Interfaces: None

Field Type Required? Default Description
guid uuid Yes -

Internal unique identifier for this application.
key string Yes -

Used as a unique key in the URL path. Key is automatically derived from the application name.

application_metadata_version

Example Json: Minimal | Full

Interfaces: None

Describes the versions associated with a given application

Field Type Required? Default Description
version string Yes -

Example: 0.2.5

application_summary

Example Json: Minimal | Full

Interfaces: None

Summary of an application sufficient for display and links

Field Type Required? Default Description
guid uuid Yes -

organization io.apibuilder.common.v0.models.reference:0.16.53 Yes -

key string Yes -

attribute

Example Json: Minimal | Full

Interfaces: None

Attributes are globally unique key which allow users to specify additional content to pass in to the code generators.

Field Type Required? Default Description
guid uuid Yes -

Internal unique identifier for this attribute.
name string Yes -

The name of the attribute. Globally unique and an 'identifier' (lower case, url safe, etc.)
description string No -

Optional description - a good description here will indicate which code generators it applies to and what effect it will have on those code generators.
audit io.apibuilder.common.v0.models.audit:0.16.53 Yes -

attribute_form

Example Json: Minimal | Full

Interfaces: None

Field Type Required? Default Description
name string Yes -

description string No -

attribute_summary

Example Json: Minimal | Full

Interfaces: None

Field Type Required? Default Description
guid uuid Yes -

Internal unique identifier for this attribute.
name string Yes -

The name of the attribute. Globally unique and an 'identifier' (lower case, url safe, etc.)

attribute_value

Example Json: Minimal | Full

Interfaces: None

Attribute values can be set at different levels. Initially we support setting organization wide attributes, but in the future plan to support setting attribute values with each version of the application.

Field Type Required? Default Description
guid uuid Yes -

Internal unique identifier for this attribute value.
attribute attribute_summary Yes -

value string Yes -

audit io.apibuilder.common.v0.models.audit:0.16.53 Yes -

attribute_value_form

Example Json: Minimal | Full

Interfaces: None

Field Type Required? Default Description
value string Yes -

authentication

Example Json: Minimal | Full

Interfaces: None

Represents the result of a successful authorization

Field Type Required? Default Description
user user Yes -

session session Yes -

batch_download_application_form

Example Json: Minimal | Full

Interfaces: None

Field Type Required? Default Description
application_key string Yes -

version string No latest

batch_download_applications

Example Json: Minimal | Full

Interfaces: None

Field Type Required? Default Description
applications [version] Yes -

batch_download_applications_form

Example Json: Minimal | Full

Interfaces: None

Field Type Required? Default Description
applications [batch_download_application_form] Yes -

change

Example Json: Minimal | Full

Interfaces: None

Represents a single change from one version of a service to another

Field Type Required? Default Description
guid uuid Yes -

organization io.apibuilder.common.v0.models.reference:0.16.53 Yes -

application io.apibuilder.common.v0.models.reference:0.16.53 Yes -

from_version change_version Yes -

to_version change_version Yes -

diff diff Yes -

changed_at date-time-iso8601 Yes -

Records the timestamp of when the actual change occurred (vs. when we created the changed record)
changed_by user_summary Yes -

Records who made the actual change
audit io.apibuilder.common.v0.models.audit:0.16.53 Yes -

change_version

Example Json: Minimal | Full

Interfaces: None

Represents a simpler model of a version specifically for the use case of displaying changes

Field Type Required? Default Description
guid uuid Yes -

version string Yes -

cleartext_token

Example Json: Minimal | Full

Interfaces: None

Separate resource used only for the few actions that require the full token.

Field Type Required? Default Description
token string Yes -

The actual token. Guaranteed to be globally unique.

code

Example Json: Minimal | Full

Interfaces: None

Generated source code.

Field Type Required? Default Description
generator generator_with_service Yes -

source string Yes -

The actual source code.

deprecated:

Use files instead
files [io.apibuilder.generator.v0.models.file:0.16.53] Yes []

A collection of source files

code_form

Example Json: Minimal | Full

Interfaces: None

Field Type Required? Default Description
attributes [io.apibuilder.generator.v0.models.attribute:0.16.53] Yes -

diff_breaking

Example Json: Minimal | Full

Interfaces: None

Represents a single breaking diff of an application version. A breaking diff indicates that it is possible for an existing client to now experience an error or invalid data due to the diff.

Field Type Required? Default Description
description string Yes -

Example: model removed: user
is_material boolean Yes -

Example: True if this is a material change (eg something important). False otherwise. This is used to drive the publication 'versions.material_change'

diff_non_breaking

Example Json: Minimal | Full

Interfaces: None

Represents a single NON breaking diff of an application version.

Field Type Required? Default Description
description string Yes -

Example: model: user optional field 'name' added
is_material boolean Yes -

Example: True if this is a material change (eg something important). False otherwise. This is used to drive the publication 'versions.material_change'

domain

Example Json: Minimal | Full

Interfaces: None

Represents a single domain name (e.g. www.apibuilder.io). When a new user registers and confirms their email, we automatically associate that user with a member of the organization associated with their domain. For example, if you confirm your account with an email address of example@somedomain.com, we will automatically create a membership request on your behalf to join the organization with domain somedomain.com.

Field Type Required? Default Description
name string Yes -

The domain name

Example: www.apibuilder.io

email_verification_confirmation_form

Example Json: Minimal | Full

Interfaces: None

Data used to confirm an email address. The token is an internal unique identifier used to lookup the specific email address and user account for which we sent an email verification email.

Field Type Required? Default Description
token string Yes -

error

Example Json: Minimal | Full

Interfaces: None

Field Type Required? Default Description
code string Yes -

Machine readable code for this specific error message
message string Yes -

Description of the error

generator_form

Example Json: Minimal | Full

Interfaces: None

Field Type Required? Default Description
service_guid uuid Yes -

generator io.apibuilder.generator.v0.models.generator:0.16.53 Yes -

generator_service

Example Json: Minimal | Full

Interfaces: None

Defines a service that provides one or more code generators

Field Type Required? Default Description
guid uuid Yes -

uri string Yes -

audit io.apibuilder.common.v0.models.audit:0.16.53 Yes -

generator_service_form

Example Json: Minimal | Full

Interfaces: None

Field Type Required? Default Description
uri string Yes -

generator_with_service

Example Json: Minimal | Full

Interfaces: None

Wraps a service and a generator providing easier access for applications.

Field Type Required? Default Description
service generator_service Yes -

generator io.apibuilder.generator.v0.models.generator:0.16.53 Yes -

item

Example Json: Minimal | Full

Interfaces: None

When searching for content, the results of the search will be a list of items. Each item will have enough information to render for the user, including a type and item_guid to enable creating the appropriate link.

Field Type Required? Default Description
guid uuid Yes -

Unique identifer for this item. By using a UUID, you can combine with the type to figure out the URI for the resource
detail item_detail Yes -

label string Yes -

description string No -

membership

Example Json: Minimal | Full

Interfaces: None

A membership represents a user in a specific role to an organization. Memberships cannot be created directly. Instead you first create a membership request, then that request is either accepted or declined.

Field Type Required? Default Description
guid uuid Yes -

Internal unique identifier for this membership.
user user Yes -

organization organization Yes -

role io.apibuilder.common.v0.enums.membership_role:0.16.53 Yes -

The role this user plays for this organization. Typically member or admin.

Example: member
audit io.apibuilder.common.v0.models.audit:0.16.53 Yes -

membership_request

Example Json: Minimal | Full

Interfaces: None

A membership request represents a user requesting to join an organization with a specific role (e.g. as a member or an admin). Membership requests can be reviewed by any current admin of the organization who can either accept or decline the request.

Field Type Required? Default Description
guid uuid Yes -

Internal unique identifier for this membership request.
user user Yes -

organization organization Yes -

role io.apibuilder.common.v0.enums.membership_role:0.16.53 Yes -

The requested role for membership to this organization. Typically member or admin.

Example: member
audit io.apibuilder.common.v0.models.audit:0.16.53 Yes -

move_form

Example Json: Minimal | Full

Interfaces: None

Field Type Required? Default Description
org_key string Yes -

The key of the organization to which we are moving this item

organization

Example Json: Minimal | Full

Interfaces: None

An organization is used to group a set of applications together.

Field Type Required? Default Description
guid uuid Yes -

Internal unique identifier for this organization.
key string Yes -

Used as a unique key in the URL path. Key is automatically derived from the organization name.
name string Yes -

The name of this organization.
namespace string Yes -

Global namespace for this organization.

Example: io.apicollective
visibility visibility Yes -

domains [domain] Yes []

audit io.apibuilder.common.v0.models.audit:0.16.53 Yes -

organization_form

Example Json: Minimal | Full

Interfaces: None

Field Type Required? Default Description
name string Yes -

key string No -

Defaults to a url friendy version of the name
namespace string Yes -

Global namespace for this organization.

Example: io.apicollective
visibility visibility Yes organization

Public organizations will be listed in apibuilder directory. Organizations with visibility organization will only be visible to members of that org.
domains [string] No -

Example: apibuilder.io

original

Example Json: Minimal | Full

Interfaces: None

Represents the original input used to create an application version

Field Type Required? Default Description
type original_type Yes -

data string Yes -

original_form

Example Json: Minimal | Full

Interfaces: None

Field Type Required? Default Description
type original_type No -

If not specified, we set the type by inspecting the data
data string Yes -

password_reset

Example Json: Minimal | Full

Interfaces: None

Allows a user to change their password with authentication from a token.

Field Type Required? Default Description
token string Yes -

Unique one time use token to change a password
password string Yes -

password_reset_request

Example Json: Minimal | Full

Interfaces: None

Create a password reset request - e.g. an email containing a one time URL to change a password

Field Type Required? Default Description
email string Yes -

The email address for which we generate the password reset.

session

Example Json: Minimal | Full

Interfaces: None

Represents a user sessions (e.g. user logged into site)

Field Type Required? Default Description
id string Yes -

Cryptographically secure session id
expires_at date-time-iso8601 Yes -

subscription

Example Json: Minimal | Full

Interfaces: None

Represents a user that is currently subscribed to a publication

Field Type Required? Default Description
guid uuid Yes -

Internal unique identifier for this subscription record
organization organization Yes -

user user Yes -

publication publication Yes -

audit io.apibuilder.common.v0.models.audit:0.16.53 Yes -

subscription_form

Example Json: Minimal | Full

Interfaces: None

Field Type Required? Default Description
organization_key string Yes -

user_guid uuid Yes -

publication publication Yes -

token

Example Json: Minimal | Full

Interfaces: None

A token gives a user access to the API.

Field Type Required? Default Description
guid uuid Yes -

Internal unique identifier for this token.
user user Yes -

The user to which this token belongs.
masked_token string Yes -

The masked from of the token.
description string No -

optional description to help the user manage the token.
audit io.apibuilder.common.v0.models.audit:0.16.53 Yes -

token_form

Example Json: Minimal | Full

Interfaces: None

Field Type Required? Default Description
user_guid uuid Yes -

The user for which we are creating the token.
description string No -

user

Example Json: Minimal | Full

Interfaces: None

A user is a top level person interacting with the api doc server.

Field Type Required? Default Description
guid uuid Yes -

Internal unique identifier for this user.
email string Yes -

nickname string Yes -

Public unique identifier for this user.
name string No -

audit io.apibuilder.common.v0.models.audit:0.16.53 Yes -

user_form

Example Json: Minimal | Full

Interfaces: None

Field Type Required? Default Description
email string Yes -

password string Yes -

nickname string No -

Defaults to a unique identifier based on email address
name string No -

user_summary

Example Json: Minimal | Full

Interfaces: None

Summary of a user sufficient for display

Field Type Required? Default Description
guid uuid Yes -

nickname string Yes -

user_update_form

Example Json: Minimal | Full

Interfaces: None

Field Type Required? Default Description
email string Yes -

nickname string Yes -

name string No -

validation

Example Json: Minimal | Full

Interfaces: None

Used only to validate json files - used as a resource where http status code defines success

Field Type Required? Default Description
valid boolean Yes -

If true, the json schema is valid. If false, there is at least one validation error.
errors [string] Yes []

Contains any validation errors that result from parsing the json document. If empty, the document is valid.

version

Example Json: Minimal | Full

Interfaces: None

Represents a unique version of the application.

Field Type Required? Default Description
guid uuid Yes -

Internal unique identifier for this version.
organization io.apibuilder.common.v0.models.reference:0.16.53 Yes -

application io.apibuilder.common.v0.models.reference:0.16.53 Yes -

version string Yes -

The tag for this version. Can be anything, but if semver style version number is used, we automatically correctly sort by version number to find latest. Otherwise latest version is considered to be the most recently created.

Example: 1.0.0
original original No -

The original uploaded file describing this version, if available
service io.apibuilder.spec.v0.models.service:0.16.53 Yes -

spec/spec.json description of this API
audit io.apibuilder.common.v0.models.audit:0.16.53 Yes -

version_form

Example Json: Minimal | Full

Interfaces: None

Field Type Required? Default Description
original_form original_form Yes -

visibility visibility No -

If provided, updates the visibility for all versions of this application

watch

Example Json: Minimal | Full

Interfaces: None

Users can watch individual applications which enables features like receiving an email notification when there is a new version of an application.

Field Type Required? Default Description
guid uuid Yes -

Internal unique identifier for this watch
user user Yes -

organization organization Yes -

application application Yes -

audit io.apibuilder.common.v0.models.audit:0.16.53 Yes -

watch_form

Example Json: Minimal | Full

Interfaces: None

Field Type Required? Default Description
user_guid uuid Yes -

organization_key string Yes -

application_key string Yes -

Unions

diff

Interfaces: diff

  • Type discriminator: type

Represents a single diff in an application

Type Discriminator Value Example Json Description
diff_breaking diff_breaking Minimal | Full

diff_non_breaking diff_non_breaking Minimal | Full

item_detail

Interfaces: None

  • Type discriminator: type

Identifies the specific type of item that was indexed by search

Type Discriminator Value Example Json Description
application_summary application_summary Minimal | Full

Represents that the item indexed was an application

Annotations

No annotations