apidoc api 0.0.5

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

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.

change

Operations

Method and Path Description
GET /changes

code

Operations

Method and Path Description
GET /:orgKey/:applicationKey/:version/:generatorKey

Generate code for a specific version of an application.

com.bryzek.apidoc.generator.v0.models.healthcheck

Operations

Method and Path Description
GET /_internal_/healthcheck
GET /_internal_/migrate

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

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

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.

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

http://www.apidoc.me/bryzek/apidoc-common/latest/service.json
http://www.apidoc.me/bryzek/apidoc-generator/latest/service.json
http://www.apidoc.me/bryzek/apidoc-spec/latest/service.json

Enums

original_type

api_json

The original is in the api.json format

avro_idl

The original is in Avro Idl format

service_json

This is the canonical service spec for apidoc itself. See http://apidoc.me/bryzek/apidoc-spec/latest#model-service

swagger_json

The original in the swagger.json 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.

membership_requests.create

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

memberships.create

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

applications.create

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

versions.create

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

visibility

Controls who is able to view this version

user

Only the creator can view this application

organization

Any member of the organization can view this application

public

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

Models

application

Example Json: Minimal | Full

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 com.bryzek.apidoc.common.v0.models.reference:0.11.80 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 -

audit com.bryzek.apidoc.common.v0.models.audit:0.11.80 Yes -

application_form

Example Json: Minimal | Full
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_summary

Example Json: Minimal | Full

Summary of an application sufficient for display and links

Field Type Required? Default Description
guid uuid Yes -

organization com.bryzek.apidoc.common.v0.models.reference:0.11.80 Yes -

key string Yes -

attribute

Example Json: Minimal | Full

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 com.bryzek.apidoc.common.v0.models.audit:0.11.80 Yes -

attribute_form

Example Json: Minimal | Full
Field Type Required? Default Description
name string Yes -

description string No -

attribute_summary

Example Json: Minimal | Full
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

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 -

radomstuff string Yes -

radomstuff2 string No -

audit com.bryzek.apidoc.common.v0.models.audit:0.11.80 Yes -

attribute_value_form

Example Json: Minimal | Full
Field Type Required? Default Description
value string Yes -

change

Example Json: Minimal | Full

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

Field Type Required? Default Description
guid uuid Yes -

organization com.bryzek.apidoc.common.v0.models.reference:0.11.80 Yes -

application com.bryzek.apidoc.common.v0.models.reference:0.11.80 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 com.bryzek.apidoc.common.v0.models.audit:0.11.80 Yes -

change_version

Example Json: Minimal | Full

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

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

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 [com.bryzek.apidoc.generator.v0.models.file:0.11.80] No []

A collection of source files

diff_breaking

Example Json: Minimal | Full

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

diff_non_breaking

Example Json: Minimal | Full

Represents a single NON breaking diff of an application version.

Field Type Required? Default Description
description string Yes -

Example: name diffd from foo to bar

domain

Example Json: Minimal | Full

Represents a single domain name (e.g. www.apidoc.me). 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 foo@bryzek.com, we will automatically create a membership request on your behalf to join the organization with domain bryzek.com.

Field Type Required? Default Description
name string Yes -

The domain name

Example: www.apidoc.me

email_verification_confirmation_form

Example Json: Minimal | Full

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
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
Field Type Required? Default Description
service_guid uuid Yes -

generator com.bryzek.apidoc.generator.v0.models.generator:0.11.80 Yes -

generator_service

Example Json: Minimal | Full

Defines a service that provides one or more code generators

Field Type Required? Default Description
guid uuid Yes -

uri string Yes -

audit com.bryzek.apidoc.common.v0.models.audit:0.11.80 Yes -

generator_service_form

Example Json: Minimal | Full
Field Type Required? Default Description
uri string Yes -

generator_with_service

Example Json: Minimal | Full

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

Field Type Required? Default Description
service generator_service Yes -

generator com.bryzek.apidoc.generator.v0.models.generator:0.11.80 Yes -

item

Example Json: Minimal | Full

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

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 string Yes -

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

Example: member

audit com.bryzek.apidoc.common.v0.models.audit:0.11.80 Yes -

membership_request

Example Json: Minimal | Full

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 string Yes -

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

Example: member

audit com.bryzek.apidoc.common.v0.models.audit:0.11.80 Yes -

move_form

Example Json: Minimal | Full
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

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: com.bryzek

visibility visibility Yes -

domains [domain] No []

audit com.bryzek.apidoc.common.v0.models.audit:0.11.80 Yes -

organization_form

Example Json: Minimal | Full
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: com.bryzek

visibility visibility No organization

Public organizations will be listed in apidoc directory. Organizations with visibility organization will only be visible to members of that org.

domains [string] No -

Example: apidoc.me

original

Example Json: Minimal | Full

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

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

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.

password_reset_success

Example Json: Minimal | Full

On a successful password reset, return some metadata about the user modified.

Field Type Required? Default Description
user_guid uuid Yes -

subscription

Example Json: Minimal | Full

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 com.bryzek.apidoc.common.v0.models.audit:0.11.80 Yes -

subscription_form

Example Json: Minimal | Full
Field Type Required? Default Description
organization_key string Yes -

user_guid uuid Yes -

publication publication Yes -

token

Example Json: Minimal | Full

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 com.bryzek.apidoc.common.v0.models.audit:0.11.80 Yes -

token_form

Example Json: Minimal | Full
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

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 com.bryzek.apidoc.common.v0.models.audit:0.11.80 Yes -

user_form

Example Json: Minimal | Full
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

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
Field Type Required? Default Description
email string Yes -

nickname string Yes -

name string No -

validation

Example Json: Minimal | Full

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] No []

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

version

Example Json: Minimal | Full

Represents a unique version of the application.

Field Type Required? Default Description
guid uuid Yes -

Internal unique identifier for this version.

organization com.bryzek.apidoc.common.v0.models.reference:0.11.80 Yes -

application com.bryzek.apidoc.common.v0.models.reference:0.11.80 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 com.bryzek.apidoc.spec.v0.models.service:0.11.80 Yes -

spec/spec.json description of this API

audit com.bryzek.apidoc.common.v0.models.audit:0.11.80 Yes -

version_form

Example Json: Minimal | Full
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

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 com.bryzek.apidoc.common.v0.models.audit:0.11.80 Yes -

watch_form

Example Json: Minimal | Full
Field Type Required? Default Description
user_guid uuid Yes -

organization_key string Yes -

application_key string Yes -

Unions

diff

Example Json: Minimal | Full
  • Type discriminator: type

Represents a single diff in an application

diff_breaking
diff_non_breaking

item_detail

Example Json: Minimal | Full
  • Type discriminator: type

Identifies the specific type of item that was indexed by search

application_summary

Represents that the item indexed was an application