apibuilder api 0.16.48 - API Collective

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

Base URL: https://api.apibuilder.io

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

License: MIT

Version:

application

Path: /:orgKey

GET /:orgKey/metadata/:applicationKey/versions

Returns the versions assocoated with the specified application. The latest version is the first result returned.

Parameters

Name	Type	Description
orgKey required	string	Path
applicationKey required	string	Path
limit required	long	Query default: 25 The number of records to return (max: 100)
offset required	long	Query default: 0 Used to paginate. First page of results is 0. (min: 0)

Responses

Code	Type	Description
200	[application_metadata_version]
401	unit
404	unit

GET /:orgKey/metadata/:applicationKey/versions/latest.txt

Returns the latest version number as a string

Parameters

Name	Type	Description
orgKey required	string	Path
applicationKey required	string	Path

Responses

Code	Type	Description
200	string
401	unit
404	unit

GET /:orgKey

Search all applications. Results are always paginated.

Parameters

Name	Type	Description
orgKey required	string	Path The organization key for which to search applications
name	string	Query The name of an application. Case in-sensitive. Exact match
guid	uuid	Query The guid of an application. Exact match
key	string	Query The key of an application. Case in-sensitive. Exact match
has_version	boolean	Query If true, we return applications that have at least one version. If false, we return applications that have no versions in the system
limit required	long	Query default: 25 The number of records to return (max: 100)
offset required	long	Query default: 0 Used to paginate. First page of results is 0. (min: 0)
sort_by	app_sort_by	Query
order	sort_order	Query

Responses

Code	Type	Description
200	[application]

POST /:orgKey

Create an application.

Body

application_form

Parameters

Name	Type	Description
orgKey required	string	Path

Responses

Code	Type	Description
200	application
409	[error]

PUT /:orgKey/:applicationKey

Updates an application.

Body

application_form

Parameters

Name	Type	Description
orgKey required	string	Path
applicationKey required	string	Path

Responses

Code	Type	Description
200	application
409	[error]

DELETE /:orgKey/:applicationKey

Deletes a specific application and its associated versions.

Parameters

Name	Type	Description
orgKey required	string	Path
applicationKey required	string	Path

Responses

Code	Type	Description
204	unit
401	unit
404	unit

POST /:orgKey/:applicationKey/move

Moves application to a new organization.

Body

move_form

Parameters

Name	Type	Description
orgKey required	string	Path
applicationKey required	string	Path

Responses

Code	Type	Description
200	application
409	[error]

attribute

Path: /attributes

GET /attributes

Search all attributes. Results are always paginated.

Parameters

Name	Type	Description
guid	uuid	Query Find the watch with this guid.
name	string	Query Find attributes with this name. Case in-sensitive. Exact match
limit required	long	Query default: 25 The number of records to return (min: 1,max: 100)
offset required	long	Query default: 0 Used to paginate. First page of results is 0. (min: 0)

Responses

Code	Type	Description
200	[attribute]

GET /attributes/:name

Returns the attribute with this name.

Parameters

Name	Type	Description
name required	string	Path

Responses

Code	Type	Description
200	attribute
404	unit

POST /attributes

Create a new attribute.

Body

attribute_form

Responses

Code	Type	Description
201	attribute
401	unit
409	[error]

DELETE /attributes/:name

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

Parameters

Name	Type	Description
name required	string	Path

Responses

Code	Type	Description
204	unit
401	unit
404	unit

authentication

Path: /authentications

GET /authentications/session/:id

Parameters

Name	Type	Description
id required	string	Path

Responses

Code	Type	Description
200	authentication
404	unit

batch

Path: /:orgKey/batch/applications

POST /:orgKey/batch/applications

Upsert multiple applications in one api call. Validation happens first - we store results only if ALL applications are valid

Body

batch_form

Parameters

Name	Type	Description
orgKey required	string	Path

Responses

Code	Type	Description
201	batch
409	[error]

POST /:orgKey/batch/applications/dryrun

Validate a batch of applications without SAVING anything to the database

Body

batch_download_form

Parameters

Name	Type	Description
orgKey required	string	Path

Responses

Code	Type	Description
201	batch
409	[error]

POST /:orgKey/batch/applications/download

Download multiple applications in one api call.

Body

batch_download_form

Parameters

Name	Type	Description
orgKey required	string	Path

Responses

Code	Type	Description
201	batch
409	[error]

change

Path: /changes

GET /changes

Parameters

Name	Type	Description
org_key	string	Query Filter changes to those made for the organization with this key.
application_key	string	Query Filter changes to those made for the application with this key.
from	string	Query Filter changes to those made from this version.
to	string	Query Filter changes to those made to this version.
type	string	Query The type of diff to return.
limit required	long	Query default: 25 The number of records to return (min: 1,max: 100)
offset required	long	Query default: 0 Used to paginate. First page of results is 0. (min: 0)

Responses

Code	Type	Description
200	[change]

code

Path: /:orgKey/:applicationKey/:version

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

Body

code_form

Parameters

Name	Type	Description
orgKey required	string	Path
applicationKey required	string	Path
version required	string	Path

Responses

Code	Type	Description
200	io.apibuilder.generator.v0.models.invocation_form
409	[error]

GET /:orgKey/:applicationKey/:version/:generatorKey

Generate code for a specific version of an application.

Parameters

Name	Type	Description
orgKey required	string	Path The organization key for which to generate code
applicationKey required	string	Path The application key for which to generate code
version required	string	Path The version of this application. Can be 'latest'
generatorKey required	string	Path The key of the generator to invoke

Responses

Code	Type	Description
200	code
409	[error]	If the target, version, and/or generator are invalid.

POST /:orgKey/:applicationKey/:version/:generatorKey

Generate code for a specific version of an application.

Body

code_form

Parameters

Name	Type	Description
orgKey required	string	Path The organization key for which to generate code
applicationKey required	string	Path The application key for which to generate code
version required	string	Path The version of this application. Can be 'latest'
generatorKey required	string	Path The key of the generator to invoke

Responses

Code	Type	Description
200	code
409	[error]	If the target, version, and/or generator are invalid.

domain

Path: /domains/:orgKey

POST /domains/:orgKey

Add a domain to this organization

Body

domain

Parameters

Name	Type	Description
orgKey required	string	Path

Responses

Code	Type	Description
200	domain
409	[error]

DELETE /domains/:orgKey/:name

Remove this domain from this organization

Parameters

Name	Type	Description
orgKey required	string	Path
name required	string	Path

Responses

Code	Type	Description
204	unit
401	unit
404	unit

email_verification_confirmation_form

Path: /email_verification_confirmations

POST /email_verification_confirmations

Validate an email address using a token.

Body

email_verification_confirmation_form

Responses

Code	Type	Description
204	unit
409	[error]

generator_service

Path: /generator_services

GET /generator_services

List all generator services

Parameters

Name	Type	Description
guid	uuid	Query
uri	string	Query
generator_key	string	Query
limit required	long	Query default: 100 The number of records to return (min: 1,max: 100)
offset required	long	Query default: 0 Used to paginate. First page of results is 0. (min: 0)

Responses

Code	Type	Description
200	[generator_service]

GET /generator_services/:guid

Parameters

Name	Type	Description
guid required	uuid	Path

Responses

Code	Type	Description
200	generator_service
404	unit

POST /generator_services

Body

generator_service_form

Responses

Code	Type	Description
200	generator_service
409	[error]

DELETE /generator_services/:guid

Deletes a generator service.

Parameters

Name	Type	Description
guid required	uuid	Path

Responses

Code	Type	Description
204	unit
401	unit
404	unit

generator_with_service

Path: /generators

GET /generators

List all available generators

Parameters

Name	Type	Description
guid	uuid	Query Filter to generator with this guid
service_guid	uuid	Query Filter to generator from this service
service_uri	string	Query Filter to generator from this service URI
attribute_name	string	Query Filter to generators that use this attribute
key	string	Query Filter to generator with this key
limit required	long	Query default: 100 The number of records to return (min: 1,max: 100)
offset required	long	Query default: 0 Used to paginate. First page of results is 0. (min: 0)

Responses

Code	Type	Description
200	[generator_with_service]

GET /generators/:key

Parameters

Name	Type	Description
key required	string	Path

Responses

Code	Type	Description
200	generator_with_service
404	unit

io.apibuilder.generator.v0.models.healthcheck

Path: /_internal_

GET /_internal_/healthcheck

Responses

Code	Type	Description
200	io.apibuilder.generator.v0.models.healthcheck

item

Path: /items

GET /items

Parameters

Name	Type	Description
q	string	Query The search query. At the moment, we do case insensitive exact match search.
limit required	long	Query default: 25 The number of records to return (min: 1,max: 100)
offset required	long	Query default: 0 Used to paginate. First page of results is 0. (min: 0)

Responses

Code	Type	Description
200	[item]

GET /items/:guid

Parameters

Name	Type	Description
guid required	uuid	Path

Responses

Code	Type	Description
200	item
404	unit

membership

Path: /memberships

GET /memberships

Search all memberships. Results are always paginated.

Parameters

Name	Type	Description
org_guid	uuid	Query
org_key	string	Query
user_guid	uuid	Query
role	io.apibuilder.common.v0.enums.membership_role	Query
limit required	long	Query default: 25 The number of records to return (min: 1,max: 100)
offset required	long	Query default: 0 Used to paginate. First page of results is 0. (min: 0)

Responses

Code	Type	Description
200	[membership]

GET /memberships/:guid

Parameters

Name	Type	Description
guid required	uuid	Path

Responses

Code	Type	Description
200	membership
404	unit

DELETE /memberships/:guid

Parameters

Name	Type	Description
guid required	uuid	Path

Responses

Code	Type	Description
204	unit
401	unit
404	unit

membership_request

Path: /membership_requests

GET /membership_requests

Search all membership requests. Results are always paginated.

Parameters

Name	Type	Description
org_guid	uuid	Query
org_key	string	Query
user_guid	uuid	Query
role	io.apibuilder.common.v0.enums.membership_role	Query
limit required	long	Query default: 25 The number of records to return (min: 1,max: 100)
offset required	long	Query default: 0 Used to paginate. First page of results is 0. (min: 0)

Responses

Code	Type	Description
200	[membership_request]

POST /membership_requests

Create a membership request

Parameters

Name	Type	Description
org_guid required	uuid	Form
user_guid required	uuid	Form
role required	io.apibuilder.common.v0.enums.membership_role	Form

Responses

Code	Type	Description
200	membership_request
409	[error]

POST /membership_requests/:guid/accept

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

Parameters

Name	Type	Description
guid required	uuid	Path

Responses

Code	Type	Description
204	unit
409	[error]

POST /membership_requests/:guid/decline

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

Parameters

Name	Type	Description
guid required	uuid	Path

Responses

Code	Type	Description
204	unit
409	[error]

organization

Path: /organizations

GET /organizations

Search all organizations. Results are always paginated.

Parameters

Name	Type	Description
guid	uuid	Query Finds the organization with this guid, if any
user_guid	uuid	Query If specified, restricts to organizations that this user is specifically a member of (e.g. will exclude public organizations with which the user does not have a direct membership).
key	string	Query Find organizations with this key. Case in-sensitive. Exact match
name	string	Query Find organizations with this name. Case in-sensitive. Exact match
namespace	string	Query Find organizations with this namespace. Case in-sensitive. Exact match
limit required	long	Query default: 25 The number of records to return (min: 1,max: 100)
offset required	long	Query default: 0 Used to paginate. First page of results is 0. (min: 0)

Responses

Code	Type	Description
200	[organization]

GET /organizations/:key

Returns the organization with this key.

Parameters

Name	Type	Description
key required	string	Path

Responses

Code	Type	Description
200	organization
404	unit

POST /organizations

Create a new organization.

Body

organization_form

Responses

Code	Type	Description
200	organization
409	[error]

PUT /organizations/:key

Update an organization.

Body

organization_form

Parameters

Name	Type	Description
key required	string	Path

Responses

Code	Type	Description
200	organization
409	[error]

DELETE /organizations/:key

Deletes an organization and all of its associated applications.

Parameters

Name	Type	Description
key required	string	Path

Responses

Code	Type	Description
204	unit
401	unit
404	unit

GET /organizations/:key/attributes

Returns all attribute values for this organization. Results are always paginated.

Parameters

Name	Type	Description
key required	string	Path
name	string	Query Find the values for the attribute with this name.
limit required	long	Query default: 25 The number of records to return (min: 1,max: 100)
offset required	long	Query default: 0 Used to paginate. First page of results is 0. (min: 0)

Responses

Code	Type	Description
200	[attribute_value]

GET /organizations/:key/attributes/:name

Returns the attribute value with this name.

Parameters

Name	Type	Description
key required	string	Path
name required	string	Path

Responses

Code	Type	Description
200	attribute_value
404	unit

PUT /organizations/:key/attributes/:name

Create or update a new attribute value.

Body

attribute_value_form

Parameters

Name	Type	Description
key required	string	Path
name required	string	Path

Responses

Code	Type	Description
200	attribute_value
201	attribute_value
404	unit
409	[error]

DELETE /organizations/:key/attributes/:name

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

Parameters

Name	Type	Description
key required	string	Path
name required	string	Path

Responses

Code	Type	Description
204	unit
401	unit
404	unit

password_reset

Path: /password_resets

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.

Body

password_reset

Responses

Code	Type	Description
200	authentication
409	[error]

password_reset_request

Path: /password_reset_requests

POST /password_reset_requests

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

Body

password_reset_request

Responses

Code	Type	Description
204	unit
409	[error]

subscription

Path: /subscriptions

GET /subscriptions

Search subscriptions. Always paginated.

Parameters

Name	Type	Description
guid	uuid	Query Find the subscription with this guid.
organization_key	string	Query Find subscriptions for this organization.
user_guid	uuid	Query Find subscriptions for this user.
publication	publication	Query Find subscriptions for this publication.
limit required	long	Query default: 25 The number of records to return (min: 1,max: 100)
offset required	long	Query default: 0 Used to paginate. First page of results is 0. (min: 0)

Responses

Code	Type	Description
200	[subscription]

GET /subscriptions/:guid

Returns information about a specific subscription.

Parameters

Name	Type	Description
guid required	uuid	Path

Responses

Code	Type	Description
200	subscription
404	unit

POST /subscriptions

Create a new subscription.

Body

subscription_form

Responses

Code	Type	Description
201	subscription
409	[error]

DELETE /subscriptions/:guid

Parameters

Name	Type	Description
guid required	uuid	Path

Responses

Code	Type	Description
204	unit
401	unit
404	unit

token

Path: /tokens

GET /tokens/users/:user_guid

Parameters

Name	Type	Description
user_guid required	uuid	Path
guid	uuid	Query
limit required	long	Query default: 25 The number of records to return (min: 1,max: 100)
offset required	long	Query default: 0 Used to paginate. First page of results is 0. (min: 0)

Responses

Code	Type	Description
200	[token]

GET /tokens/:guid/cleartext

Used to fetch the clear text token.

Parameters

Name	Type	Description
guid required	uuid	Path

Responses

Code	Type	Description
200	cleartext_token
404	unit

POST /tokens

Create a new API token for this user

Body

token_form

Responses

Code	Type	Description
201	token
409	[error]

DELETE /tokens/:guid

Parameters

Name	Type	Description
guid required	uuid	Path

Responses

Code	Type	Description
204	unit
401	unit
404	unit

user

Path: /users

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.

Parameters

Name	Type	Description
guid	uuid	Query Find user with this guid. Exact match
email	string	Query Find user with this email address. Case in-sensitive. Exact match
nickname	string	Query Find user with the specified nickname. For users that register via GitHub, this will be their GitHub username. Case in-sensitive. Exact match
token	string	Query Find the user with this API token. Exact match

Responses

Code	Type	Description
200	[user]

GET /users/:guid

Returns information about the user with this guid.

Parameters

Name	Type	Description
guid required	uuid	Path

Responses

Code	Type	Description
200	user
404	unit

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.

Parameters

Name	Type	Description
email required	string	Form
password required	string	Form

Responses

Code	Type	Description
200	authentication
409	[error]

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

Parameters

Name	Type	Description
token required	string	Form The GitHub assigned oauth token

Responses

Code	Type	Description
200	authentication
409	[error]

POST /users

Create a new user.

Body

user_form

Responses

Code	Type	Description
200	user
409	[error]

PUT /users/:guid

Updates information about the user with the specified guid.

Body

user_update_form

Parameters

Name	Type	Description
guid required	uuid	Path

Responses

Code	Type	Description
200	user
409	[error]

validation

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

Path: /validations

POST /validations

Body

string

Responses

Code	Type	Description
200	validation

version

Path: /:orgKey

GET /:orgKey/:applicationKey

Search all versions of this application. Results are always paginated.

Parameters

Name	Type	Description
orgKey required	string	Path The organization key for which to search versions
applicationKey required	string	Path The application key for which to search versions
limit required	long	Query default: 25 The number of records to return (max: 100)
offset required	long	Query default: 0 Used to paginate. First page of results is 0. (min: 0)

Responses

Code	Type	Description
200	[version]

GET /:orgKey/:applicationKey/:version

Retrieve a specific version of an application.

Parameters

Name	Type	Description
orgKey required	string	Path
applicationKey required	string	Path
version required	string	Path The version of this application to download, or the keyword latest to get the latest version

Responses

Code	Type	Description
200	version
404	unit

POST /:orgKey/:version

Create a new version for an application

Body

version_form

Parameters

Name	Type	Description
orgKey required	string	Path
version required	string	Path

Responses

Code	Type	Description
200	version
409	[error]

PUT /:orgKey/:applicationKey/:version

Upsert a version of an application

Body

version_form

Parameters

Name	Type	Description
orgKey required	string	Path
applicationKey required	string	Path
version required	string	Path

Responses

Code	Type	Description
200	version
409	[error]

DELETE /:orgKey/:applicationKey/:version

Deletes a specific version.

Parameters

Name	Type	Description
orgKey required	string	Path
applicationKey required	string	Path
version required	string	Path

Responses

Code	Type	Description
204	unit
401	unit
404	unit

GET /:orgKey/:applicationKey/:version/example/:type_name

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

Parameters

Name	Type	Description
orgKey required	string	Path
applicationKey required	string	Path
version required	string	Path The version of this application to download, or the keyword latest to get the latest version
type_name required	string	Path The name of the type (e.g. model name) for which you would like to generate a sample json document
sub_type_name	string	Query The name of the sub-type for which you would like to generate a sample json document, e.g. a specific type of a union
optional_fields	boolean	Query If true, we generate sample data for all optional fields. Otherwise the generated sample will contain only required fields, where applicable

Responses

Code	Type	Description
200	object
404	unit

watch

Path: /watches

GET /watches

Search attributes. Always paginated.

Parameters

Name	Type	Description
guid	uuid	Query Find the watch with this guid.
user_guid	uuid	Query Find attributes for this user.
organization_key	string	Query Find attributes for this organization.
application_key	string	Query Find attributes for this application.
limit required	long	Query default: 25 The number of records to return (min: 1,max: 100)
offset required	long	Query default: 0 Used to paginate. First page of results is 0. (min: 0)

Responses

Code	Type	Description
200	[watch]

GET /watches/:guid

Returns information about a specific watch.

Parameters

Name	Type	Description
guid required	uuid	Path

Responses

Code	Type	Description
200	watch
404	unit

GET /watches/check

Quick check if a user is watching a specific application.

Parameters

Name	Type	Description
user_guid	uuid	Query The user for which we are checking. API returns false if the user guid is not provided
organization_key required	string	Query
application_key required	string	Query

Responses

Code	Type	Description
200	boolean

POST /watches

Create a new watch.

Body

watch_form

Responses

Code	Type	Description
201	watch
409	[error]

DELETE /watches/:guid

Parameters

Name	Type	Description
guid required	uuid	Path

Responses

Code	Type	Description
204	unit
401	unit
404	unit