Overview

This document describes the resources that are accessible through the BuildBotics API.

This section describes the details of the protocol and the following sections describe individual data models and their API calls.

Schema

All API access is over HTTP, and accessed from the root URL http://buildbotics.org/api/. All data is sent and received as JSON.

In the API docmentation the root URL and HTTP version are left off. So for example:

PUT /users/{name}/follow

is actually:

PUT http://buildbotics.org/api/users/{name}/follow HTTP/1.1

Parameters

API methods may take optional parameters. These request parameters may be specified as follows:

URL parameters as part of the URL path.
As HTTP query string parameters.
As JSON encoded data with Content-Type: application/json.

URL parameters are specified using curly braces. For example:

PUT /users/{name}/follow

In the above case {name} is a URL parameter.

For POST, PUT and DELETE request parameters not included in the URL path should be encoded as JSON.

Types

This section describes how data types are defined in this document.

Notation

Types are denoted in this document by a keyword enclosed with < and >. For example: <name> or <integer>.

Compound types are defined a dictionaries of keywords followed by their type definition. For example:

{
  a: <string>
  b: <bool>
  c: <integer>
}

Inheritance

Data model inheritance is denoted as follows:

<child>(<parent>) = {
  # Child property definitions here
}

Meaning the <child> model being defined, inherits all the properties of <parent> model.

Ranges

Type definitions may be followed by range definitions. For example:

(0,64)

In the case of a number, this indicates the numbers range is from 0 to 64 inclusive. In the case of a string or array it refers to it's length.

Model Comments

Type definitions may also include comments which follow a # sign. For example a complete type definition may appear as follows:

{
  a: <string> (2,120) # A string, 2 to 120 characters long.
  b: <bool>
  c: <integer> (0,100) # An integer in the range 0 to 100 inclusive.
}

Names

<name> = <string> (2,64) # Matching regex [A-Za-z0-9][A-Za-z0-9_-]{1,63}

A <name> is a <string> with length (2,64) containing only [A-Za-z0-9_-] and not starting with '_' or '-'.

References

<ref> = <name>/<name>

A <ref> references a thing as owner name slash thing name. For example, jimmy/fun_with_lasers.

Dates

<date> = <string> # In ISO 8601 format

All dates and times are in ISO 8601 format :YYYY-MM-DDTHH:MM:SSZ

Email Addresses

<email_address> = <string> # In RFC 28822 Section 3.4.1 format

Email addressees are formatted as described in RFC 2822 Section 3.4.1.

Markdown

<markdown> = <string> (0,10KiB) # In Markdown format

Many text fields are in Markdown format. GitHub flavored markdown is also allowed.

Media types

<media_type> = <string> # As defined by iana.org

Media types, AKA mime types, are defined by iana.org.

Errors

In case of error, HTTP status codes are returned. These codes are defined by RFC 2068 Section 10 and RFC 4918 Section 11.

Possible errors include:

400 Bad Request in case of malformed JSON input.
403 Forbidden or 404 Not Found in case of an authorization error.
404 Not Found in case a request resource does not exist.
405 Method Not Allowed in case of an invalid or unsupported API call.
422 Unprocessable Entity in case of semantically incorrect input.
503 Service Unavailable rate limit exceeded.

Other HTTP error codes may be returned where appropriate.

More details about an error may be returned as JSON data defined as follows:

<errors> = [<error>...]

<error> = {
  message: <string>
  code: <integer>
  field: <name> # (Optional) The name of the field in error.
}

Error Codes

Error Code	Description
required	The specified field is not optional.
invalid	The specified field is invalid.
exists	The resource already exists and cannot be created.

HTTP Verbs

This API uses the following HTTP Verbs as described below.

GET - Get a resource or list of resources.
POST - Create a new resource for which the name is not yet known.
PUT - Create or modify an resource for which the name is known.
DELETE - Delete an existing resource by name.

Authentication

Authentication is provided by third-party providers exclusively. These are as follows:

Provider	Type
Google+	OAuth 2.0 API
Facebook	OAuth 2.0 API
GitHub	OAuth 2.0 API
Twitter	OAuth 1.0a API

One or more of these third-parties may be used to associate logins and verified email addresses with the BuildBotics API.

Authorization

Various API calls require different levels of authorization. Authorization is handled through the badge system and ownership. For example, adding a new license type might require the admin badge whereas editing a project would require that either the user is the owner or has a badge sufficient to override the ownership requirement.

In case a user attempts an operation for which they are not authorized, a 403 Forbidden or possibly 404 Not Found HTTP response code will be returned.

Pagination

Request which return multiple items are paginated. By default 20 items are returned per call. Each item is supplied with an offset key which tells where it is in the stream.

Parameters

Name	Type	Description
limit	`<integer>` (1,100)	Default 30. Items per page.
next	`<string>`	Key of the item just before the requested page.
prev	`<string>`	Key of the item just after the requested page.

Either next or prev may be provided but not both. Both parameters should be copied from the <owner>/<name> of a previous request.

Rate Limiting

Rate limits are as follows:

User	Max Requests in Past 5 Minutes
Unauthenticated	50
Authenticated	200

If you exceed the rate limit 503 Service Unavailable will be returned.

Authenticate

GET /auth/{provider}

Where {provider} is one of:

google
facebook
twitter
github

GET /auth/{provider}/callback

Logout

GET /auth/logout

Get Active User Profile

GET /auth/user

Response

<profile>

null

Users

Profile Model

User profiles are defined as follows:

<profile> = {
  owner: <name>
  joined: <date>
  fullname: <string> (0,120)
  location: <string> (0,255)
  avatar: <url>
  bio: <markdown>
  url: <url>
  followers: <integer>
  following: <integer>
  stars: <integer>
  points: <integer>
  badges: <integer>
}

Get user profile

GET /users/{name}

Example

Request

GET /users/johndoe HTTP/1.1

Response

Status: 200 OK
Content-Type: application/json

{
  owner: "johndoe",
  joined: "2014-09-27T07:15:05Z",
  fullname: "John Doe",
  avatar: "http://example.com/~johndoe/images/johndoe.png",
  bio: "John is an avid builder...",
  url: "http://example.com/~johndoe/",
  followers: 2,
  following: 2,
  stars: 10,
  points: 10305,
  badges: 1
}

Update user profile

PUT /users/{name}

Parameters

Name	Type	Description
avatar	`<url>`	URL to user's avatar.
bio	`<markdown>`	User's public biography.
url	`<url>`	Link to user's home page.
disabled	`<bool>`	Disable the account.

Other profile parameters cannot be changed with this API call.

Example

PUT /users/johndoe HTTP/1.1

{
  bio: "I like turtles.",
  url: "http://example.com/~johndoe/",
}

Status: 200 OK

List who a user is following

GET /users/{name}/following

List user followers

GET /users/{name}/followers

Follow User

PUT /users/{name}/follow

Example

PUT /users/johndoe/follow HTTP/1.1

Status: 200 OK

Unfollow User

DELETE /users/{name}/follow

Example

DELETE /users/johndoe/follow HTTP/1.1

Status: 200 OK

List user stars

GET /users/{user}/stars

Response

{
  projects: [<ref>...]
  machines: [<ref>...]
  tools: [<ref>...]
}

A list of projects the user has starred.

List user badges

GET /users/{user}/badges

Grant a badge

PUT /users/{user}/badges/{badge}

Revoke a badge

DELETE /users/{user}/badges/{badge}

Parameters

Name	Type	Description
reason	`<markdown>`	The reason the badge was revoked.

Settings

Settings Model

<settings> = {
  accounts: [<account>...]
  email: [<email>...] (0,8)
  notifications: <notifications>
}

<account> = {
  type: <string>  # google, twitter, facebook, github
  id: <string>
  primary: <bool>
}

<email> = {
  address: <email_address>
  verified: <bool>
  primary: <bool>
}

<notifications> = {
  enabled: <bool>
  project_comments: <bool>
  project_starred: <bool>
  when_followed: <bool>
  comment_referenced: <bool>
  stared_project_updates: <bool>
  stared_project_comments: <bool>
}

Associate an account

PUT /accounts/{type}

Only one account of each type can be associated at a time.

Parameters

Name	Type	Description
id	`<string>`	Account ID
primary	`<bool>`	Is the primary account?

Disassociate an account

DELETE /accounts/{type}

Must not be the primary account.

Get email addresses

GET /emails

Add email address

PUT /emails/{email_address}

Parameters

Name	Type	Description
primary	`<bool>`	Make this the primary email address.

Remove email address

DELETE /emails/{email_address}

Get notification settings

GET /notifications

Set notification settings

PUT /notifications

Parameters

Name	Type	Description
enabled	`<bool>`	Enable or disable all notifications.
project_comments	`<bool>`	Comments on the owner's project.
project_starred	`<bool>`	Stars on the owner's project.
project_duplicated	`<bool>`	When a project is duplicated.
when_followed	`<bool>`	Someone followed the owner.
comment_referenced	`<bool>`	The owner's comment was referenced.
stared_project_updates	`<bool>`	A project the owner starred was updated.
stared_project_comments	`<bool>`	A project the owner starred was commented.

Things

a <thing> is an abstract model from which <project>, <machine> and <tool> inherit.

Thing Model

<thing> = {
  name: <name>
  owner: <name>
  creation: <date>
  modified: <date>
  parent: <ref>
  published: <bool>
  url: <url>
  license: <string> (2,120)
  brief: <markdown> (0,200)
  description: <markdown>
  comments: <integer>
  stars: <integer>
  tags: [<tag>...] (0,64)
  duplications: <integer>
  files: [<file>..] (0,64)
}

Get a list of things

GET /users/{user}/projects
GET /users/{user}/machines
GET /users/{user}/tools
GET /users/{user}/tools/{tool}/children

See Search.

Create or update a thing

PUT /users/{user}/projects/{project}
PUT /users/{user}/machines/{machine}
PUT /users/{user}/tools/{tool}
PUT /users/{user}/tools/{tool}/children/{tool}

Parameters

Name	Type	Description
url	`<url>`	A URL to more information about the thing.
license	`<string>`	One of the available license names.
published	`<bool>`	True to publish the thing publicly.
description	`<markdown>`	The thing description.

Get a thing

GET /users/{user}/projects/{project}
GET /users/{user}/machines/{machine}
GET /users/{user}/tools/{tool}
GET /users/{user}/tools/{tool}/children/{tool}

Rename a thing

PUT /users/{user}/projects/{project}
PUT /users/{user}/machines/{machine}
PUT /users/{user}/tools/{tool}
PUT /users/{user}/tools/{tool}/children/{tool}

Parameters

Name	Type	Description
name	`<name>`	The new thing name.

Duplicate a thing

PUT /users/{user}/projects/{project}
PUT /users/{user}/machines/{machine}
PUT /users/{user}/tools/{tool}

Parameters

Name	Type	Description
ref	`<ref>`	A reference to the parent owner and thing.

Delete a thing

DELETE /users/{user}/projects/{project}
DELETE /users/{user}/machines/{machine}
DELETE /users/{user}/tools/{tool}
DELETE /users/{user}/tools/{tool}/children/{tool}

List thing stars

GET /users/{user}/projects/{project}/stars
GET /users/{user}/machines/{machine}/stars
GET /users/{user}/tools/{tool}/stars

Response

[<name>...]

A list of users who have starred this thing.

Star a thing

PUT /users/{user}/projects/{project}/star
PUT /users/{user}/machines/{machine}/star
PUT /users/{user}/tools/{tool}/star

Unstar a thing

DELETE /users/{user}/projects/{project}/star
DELETE /users/{user}/machines/{machine}/star
DELETE /users/{user}/tools/{tool}/star

Tag a thing

PUT /users/{user}/projects/{project}/tags/{tag}
PUT /users/{user}/machines/{machine}/tags/{tag}
PUT /users/{user}/tools/{tool}/tags/{tag}

Untag a thing

DELETE /users/{user}/projects/{project}/tags/{tag}
DELETE /users/{user}/machines/{machine}/tags/{tag}
DELETE /users/{user}/tools/{tool}/tags/{tag}

Projects

Project Model

Inherits from the thing abstract model.

<project>(<thing>) = {
  machine: <ref>
  tools: {<integer>: <ref>...] (0,64)
  workpiece: <workpiece>
  steps: [<step>...] (0,64)
}

<workpiece> = {
  material: <image>
  dimensions: <vector>
  offset: <vector>
}
<vector> = {
  x: <real>
  y: <real>
  z: <real>
}

Steps

Step Model

<step> = {
  name: <name>
  brief: <markdown> (0,200)
  description: <markdown>
  comments: <integer>
  files: [<string>...] (0,8)
}

Create or update a step

PUT /users/{user}/projects/{project}/steps/{step}

Parameters

Name	Type	Description
description	`<markdown>`	The step description.
video	`<url>`	The step video.

Only approved video URLs are allowed.

Rename a step

PUT /users/{user}/projects/{project}/steps/{step}

Parameters

Name	Type	Description
name	`<name>`	The new step name.

Reorder a step

PUT /users/{user}/projects/{project}/steps/{step}

Parameters

Name	Type	Description
position	`<integer>`	Required. New position of the step.

Delete a step

DELETE /users/{user}/projects/{project}/steps/{step}

Machines

Machine Model

Inherits from the thing abstract model.

<machine>(<thing>) = {
  type: <string>          # "cnc", "3d_printer", "laser", "plasma", "lathe"
  units: <string>         # "imperial" or "metric"
  rotation: <string>      # "degrees" or "radians"
  max_rpm: <real>         # Maximum rotational speed
  spin_up: <real>         # Rate of spin up in RPM/sec
  axes: [<axis>...] (1,9)
}

<axis> = {
  name: <string>        # "x", "y", "z", "a", "b", "c", "u", "v" or "w"
  min: <real>           # in, mm, deg, radians
  max: <real>           # in, mm, deg, radians
  step: <real>          # in or mm
  rapid_feed: <real>    # in/sec or mm/sec
  cutting_feed: <real>  # in/sec or mm/sec
  ramp_up: <real>       # in/sec/sec or mm/sec/sec
  ramp_down: <real>     # in/sec/sec or mm/sec/sec
}

Create or update a machine

PUT /users/{user}/machines/{machine}

Parameters

Name	Type	Description
type	`<string>`	A machine type.
units	`<string>`	`"imperial"` or `"metric"`.
rotation	`<string>`	`"degrees"` or `"radians"`.
max_rpm	`<real>`	Maximum rotational speed.
spin_up	`<real>`	Rate of spin up in RPM/sec.

Create or update an Axis

PUT /users/{user}/machines/{machine}/axes/{axis}

Parameters

Name	Type	Description
min	`<real>`	Minimum position of axis.
max	`<real>`	Maximum position of axis.
step	`<real>`	Minimum step.
rapid_speed	`<real>`	Fastest rapid speed.
cutting_speed	`<real>`	Fastest cutting speed.
ramp_up	`<real>`	Ramp up rate.
ramp_down	`<real>`	Ramp down rate.

Delete an Axis

DELETE /users/{user}/machines/{machine}/axes/{axis}

Tools

Tool Model

<tool>(<thing>) = {
  type: <string>         # "cylindrical", "conical", "ballnose",
                         # "spheroid" or "composite"
  units: <string>        # "imperial" or "metric"
  length: <real>         # Length of cutter
  diameter: <real>       # Diameter a base
  nose_diameter: <real>  # Diameter a tip
  flutes: <integer>      # Number of flutes
  flute_angle: <real>    # Rake angle of the flute
  lead_angle: <real>     # Angle between cutting edge & perpendicular plane
  max_doc: <real>        # Maximum depth of cut
  max_woc: <real>        # Maximum width of cut
  max_rpm: <real>        # Maximum rotational speed
  max_feed: <real>       # Maximum feed rate
  offset: <real>         # Composite tool children only
  children: [<tool>...]} # Composite tools only
}

Create or update a tool

PUT /users/{user}/tools/{tool}
PUT /users/{user}/tools/{tool}/children/{tool}

Parameters

Name	Type	Description
type	`<string>`	Tool type.
units	`<string>`	"imperial" or "metric"
length	`<real>`	Length of cutting area.
diameter	`<real>`	Diameter at base of cutting area.
nose_diameter	`<real>`	Diameter at tip of cutting area.
flutes	`<integer>`	Number of flutes.
lead_angle	`<real>`	Flute lead angle.
max_doc	`<real>`	Maximum depth of cut
max_woc	`<real>`	Maximum width of cut
max_rpm	`<real>`	Maximum rotational speed
max_feed	`<real>`	Maximum feed rate
offset	`<real>`	Maximum feed rate

Comments

Comment Model

<comment> = {
  id: <integer>
  owner: <name>
  creation: <date>
  modified: <date>
  ref: <integer>   # A reference to a previous comment.
  text: <markdown>
  deleted: <bool>  # True if the comment was marked as deleted.
}

List comments

GET /users/{user}/projects/{project}/comments
GET /users/{user}/projects/{project}/steps/{step}/comments
GET /users/{user}/machines{machine}/comments
GET /users/{user}/tools/{tool}/comments

Name	Type	Description
ref	`<integer>`	A reference to an existing comment.
text	`<markdown>`	Required. The comment text.

Update a comment

PUT /users/{user}/projects/{project}/comments/{comment}
PUT /users/{user}/projects/{project}/steps/{step}/comments/{comment}
PUT /users/{user}/machines/{machine}/comments/{comment}
PUT /users/{user}/tools/{tool}/comments/{comment}

Parameters

Name	Type	Description
text	`<markdown>`	The updated comment text.

Mark a comment deleted

DELETE /users/{user}/projects/{project}/comments/{comment}
DELETE /users/{user}/projects/{project}/steps/{step}/comments/{comment}
DELETE /users/{user}/machines/{machine}/comments/{comment}
DELETE /users/{user}/tools/{tool}/comments/{comment}

Files

File Model

<file> = {
  name: <string> (1,256)
  type: <media_type>
  creation: <date>
  url: <url>
  downloads: <integer>
  caption: <string> (0,120)
  display: <bool>   # Images only
}

Actual file data is stored in Amazon S3 storage. Requests to upload or change the contents of a file will generate a signed S3 URL and authorization parameters for file upload.

A file's <media_type> must match its file name extensions according to Amazon's File Extension to Mime Types table.

Upload or update a file

PUT /users/{user}/projects/{project}/files/{file}
PUT /users/{user}/projects/{project}/steps/{step}/files/{file}
PUT /users/{user}/machines/{machine}/files/{file}
PUT /users/{user}/tools/{tool}/files/{file}

Parameters

Name	Type	Description
caption	`<string> (0,120)`	The file caption.
display	`<bool>`	Images only*. Display this image.
position	`<integer>`	The file position.

Response

Name	Type	Description
url	`<url>`	S3 file upload URL.
key	`<string>`	S3 key.
acl	`<string>`	S3 ACL.
policy	`<string>`	S3 policy.
signature	`<string>`	S3 signature.
access	`<string>`	S3 access key.

Rename a file

PUT /users/{user}/projects/{project}/files/{file}
PUT /users/{user}/projects/{project}/steps/{step}/files/{file}
PUT /users/{user}/machines/{machine}/files/{file}
PUT /users/{user}/tools/{tool}/files/{file}

Name	Type	Description
name	`<name>`	The new file name.

Delete a file

DELETE /users/{user}/projects/{project}/files/{file}
DELETE /users/{user}/projects/{project}/steps/{step}/files/{file}
DELETE /users/{user}/machines/{machine}/files/{file}
DELETE /users/{user}/tools/{tool}/files/{file}

Events

Event Model

<event> = {
  type: <string>
  timestamp: <date>
  owner: <name>
  target: <name>
  url: <url>
  summary: <markdown>
  offset: <string>
}

Event Types

Name	Description
publish	Someone published a new project.
update	Someone updated a project.
tag	Someone tagged a project.
untag	Someone untagged a project.
comment	Someone posted a comment.
star	Someone starred a project.
follow	Someone followed a user.
unfollow	Someone unfollowed a user.
grant	A new badge was granted.
revoke	A badge was revoked.

Event Parameters

Name	Type	Description
limit	`<integer>`	Limit the number of events returned.
before	`<string>`	Return events before this offset.
after	`<string>`	Return events after this offset.

View your events

GET /events

View events

GET /users/{user}
GET /users/{user}/projects/{project}
GET /users/{user}/machines/{machine}
GET /users/{user}/tools/{tool}

Badges

Badge Model

<badge> = {
  name: <name>
  points: <integer>
  description: <markdown>
}

Get a list of badges

GET /badges

Create a new badge

PUT /badges/{badge}

Delete a badge

DELETE /badges/{badge}

Licenses

License Model

<license> = {
  name: <string> (2,120)
  url: <url>
  brief: <markdown> (0,200)
  text: <markdown>
  shareable: <bool>
  commercial_use: <bool>
  attribution: <bool>
}

Get a list of licenses

GET /licenses

Create or update a license

PUT /licenses/{license}

Parameters

Name	Type	Description
url		URL to license.
brief		Brief description of license.
text		Full text of license.
shareable		Does this license allow sharing.
commercial_use		Does this license allow commercial use.
attribution		Does this license require attribution.

Delete a license

DELETE /licenses/{license}

Search

Pagination parameters apply to all search operations.

Search for users

GET /users

Name	Type	Description
query	`<string>`	Search string.
order_by	`<string>`	`points`, `followers`, `joined`

Search for things

GET /projects
GET /machines
GET /tools
GET /users/{user}/projects
GET /users/{user}/machines
GET /users/{user}/tools

Parameters

Name	Type	Description
query	`<string>`	Search string.
license	`<string>`	Restrict to specified license.
tags	`<string>`	Restrict to specified tags.
order_by	`<string>`	`stars`, `creation`, `modified`

Buildbotics API

Overview

Schema

Parameters

Types

Notation

Inheritance

Ranges

Model Comments

Names

References

Dates

Email Addresses

Markdown

Media types

Errors

Error Codes

HTTP Verbs

Authentication

Authorization

Pagination

Parameters

Rate Limiting

Authenticate

Login

Login Callback

Logout

Get Active User Profile

Response

Users

Profile Model

Get user profile

Example

Request

Response

Update user profile

Parameters

Example

List who a user is following

List user followers

Follow User

Example

Unfollow User

Example

List user stars

Response

List user badges

Grant a badge

Revoke a badge

Parameters

Settings

Settings Model

Associate an account

Parameters

Disassociate an account

Get email addresses

Add email address

Parameters

Remove email address

Get notification settings

Set notification settings

Parameters

Things

Thing Model

Get a list of things

Create or update a thing

Parameters

Get a thing

Rename a thing

Parameters

Duplicate a thing

Parameters

Delete a thing

List thing stars

Response

Star a thing

Unstar a thing

Tag a thing

Untag a thing

Projects