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.

Intro

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

Authentication

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? && a.credentials['token'] == token
  end
  return nil
end

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

Errors

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.

Projects

GET /projects

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=abc123      # return projects that are using this theme name (slug of theme)
  &blueprint_title=1 # return projects that are using this blueprint (ID 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

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
preview_url       # Base URL to where the project is published
publish_url       # Base URL where the preview lives
type              # Type of project: graphic or app
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

GET /projects/<id or slug>

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
output            # Shell output from the last build; superuser only

GET /projects/<id or slug>/embed_code

Get an HTML embed code

POST /projects

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.

{
  "title": "foo bar",   # required
  "blueprint_id": 1,    # required
  "theme": "vox",   # required
  "slug": "foo-bar",
  "data": {}
}

After creation, an upgrade and build are automatically triggered.

PUT /projects/<id or slug>

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.

GET /projects/<id or slug>/update_snapshot

Upgrade a project to the current version of the blueprint.

GET /projects/<id or slug>/build

Trigger a preview build of the project and deploy

GET /projects/<id or slug>/build_and_publish

Trigger a published build of the project and deploy

Blueprints

TK