-
Notifications
You must be signed in to change notification settings - Fork 33
Web API
Autotune has a Web API built for the front-end javascript app. It can be used by other applications to do anything you're able to do with the Web UI.
The API endpoints exactly map to the application URLs you see when navigating the application. The API is entirely JSON-based. All data is returned as JSON, all request data must be JSON-formatted.
All requests must set the Accept header:
Accept: application/json
All POST, PUT, PATCH requests must set the Content-Type header:
Content-Type: application/json
Autotune requires a simple bearer token in your HTTP headers for API access:
Authorization: API-KEY auth=ABC123
You can create a machine account for accessing the API with the create_superuser rake task:
$ rake autotune:create_superuser[[email protected]]
Superuser with name 'autobot_machine' and email '[email protected]':
User ID: 1
API key: abc123
You can grab the API key of an existing user with the get_api_key rake task:
$ rake autotune:get_api_key[[email protected]]
Account with name 'autobot_machine' and email '[email protected]':
User ID: 1
API key: abc123
In production, API requests must go over HTTPS. The API is not designed to be secure over unencrypted connections.
Custom authorization headers
You can change how Autotune handles Authorization headers by adding a lambda method to the Autotune.configuration.verify_authorization_header configuration option. The new method should take one parameter (the contents of the Authorization header) and return an Autotune::User object.
In your config/initializers/autotune.rb add something like:
Autotune.configuration.verify_authorization_header = lambda do |auth_header|
if auth_header =~ /^CHORUS-SESSION-TOKEN/
token = /token="?(\w+)"?/.match(auth_header)[1]
uid = /uid="?(\d+)"?/.match(auth_header)[1]
auth = Autotune::Authorization.find_by_uid(uid)
return auth.user if auth.present? && auth.credentials['token'] == token
end
return nil
endUsing this example, Autotune will handle Authorization headers in the format:
Authorization: CHORUS-SESSION-TOKEN uid=123, token=foobar
Which is how Vox Media allows API calls to Autotune from other parts of Chorus.
The API will emit appropriate HTTP status codes if there are errors: 4xx errors if the problem is with the request, 500 if there is an error on the server, 2xx for success.
Errors that result from a bad request (4xx) will include a JSON payload with an error attribute:
{ "error": "Some message" }
These error messages are intended to be presented directly to the user.
Return a list of projects, sorted reverse chronologically by last update time.
API query options (all are optional)
/projects
?page=1 # return x page of results
&per_page=15 # return x number of results per page
&theme=vox # return projects that are using this theme name (slug of theme)
&blueprint=quiz # return projects that are using this blueprint (slug of blueprint)
&pub_status=draft # return only draft or only published projects (draft or published)
&search=foo # return projects with names and/or authors matching this string
&group=vox # return projects that belong to a particular group (slug of group)
Response format
The JSON payload of the response is an array of objects. Each object has the following attributes:
status # Project status: new, built, building, updating, broken
id # ID of this project
slug # Slug of this project
title # Title of this project
built # True if this project has ever been built successfully
preview_url # Base URL where the preview lives
publish_url # Base URL to where the project is published
type # Type of project: graphic or app
screenshot_sm_url # Complete url to a small breakpoint screenshot
screenshot_lg_url # Complete url to a large breakpoint screenshot
screenshot_md_url # Complete url to a medium breakpoint screenshot
screenshot_sm2x_url # Complete url to a small breakpoint HiDPI screenshot
screenshot_lg2x_url # Complete url to a large breakpoint HiDPI screenshot
screenshot_md2x_url # Complete url to a medium breakpoint HiDPI screenshot
blueprint_id # ID of the blueprint used by this project
blueprint_title # Full title of the blueprint used by this project
blueprint_version # Version of the blueprint that project is locked to
theme # Slug of the theme
created_by # Full name of the user who created this
user_id # ID of the user who created this
created_at # When this project was created
updated_at # When this project was last changed
published_at # When this project was published
data_updated_at # When the form data in this project was last changed
embed_html # HTML embed code
Return a project.
Response format
# Includes all attributes returned in the list above, plus these...
blueprint_config # Contains all the config data for the blueprint (contents of autotune-config.json)
slug_sans_theme # Version of the slug with the leading theme name removed
data # The data for populating the form
error_message # Error message for the user, if available
output # Shell output from the last build; superuser only
Create a new project
JSON Payload
While it's possible to include all fields in the payload for creating or updating, all but a few fields are ignored. The fields title, blueprint and theme are required.
{
"title": "foo bar",
"blueprint": "quiz",
"theme": "vox",
"slug": "foo-bar",
"data": {}
}After creation, an upgrade and build are automatically triggered.
Update a project
JSON Payload
While it's possible to include all fields in the payload for creating or updating, all but a few fields are ignored.
{
"title": "foo bar",
"theme": "vox",
"slug": "foo-bar",
"data": {}
}The data element overwrites everything saved in the project. It does not merge anything.
After an update, a build is automatically triggered.
Upgrade a project to the current version of the blueprint.
Trigger a preview build of the project and deploy
Trigger a published build of the project and deploy
Return a list of blueprints, sorted reverse chronologically by last update time.
API query options (all are optional)
/blueprints
?type=app # filter by blueprint type (app or graphic)
&status=ready # filter by blueprint status (new, updating, testing, ready, broken)
&search=foo # return blueprints with titles matching this string
Response format
The JSON payload of the response is an array of objects. Each object has the following attributes:
status # blueprint status: new, testing, ready, updating, broken
id # ID of this blueprint
slug # Slug of this blueprint
title # Title of this blueprint
repo_url # URL of git repo where blueprint code is stored
thumb_url # URL for a blueprint preview image
type # Type of blueprint: graphic or app
config # Contents of the blueprint's autotune-config.json configuration file
version # Git commit hash representing the latest version loaded by autotune
created_at # When this blueprint was created
updated_at # When this blueprint was last changed
Return a blueprint.
Response format matches format used in the list API call above.
Create a new blueprint
JSON Payload
The fields title and repo_url are required.
{
"title": "foo bar",
"repo_url": "[email protected]:voxmedia/autotune-example-blueprint.git",
"slug": "foo-bar"
}After creation, a repo update is automatically triggered.
Update a blueprint
JSON Payload
There are no required fields for updates.
{
"title": "foo bar",
"repo_url": "[email protected]:voxmedia/autotune-example-blueprint.git",
"slug": "foo-bar",
"status": "ready"
}Upgrade the blueprint to the the latest version in the git repository.