O’Reilly Atlas API

O’Reilly Atlas comes with a API that can be used to perform most of the tasks that can be triggered via the UI. This makes it possible to build external services on top of the platform.

Authentication

To use the API, you will need to obtain an API token from the Atlas UI. You can then use this token as a parameter when accessing the API. All routes in Atlas require an auth_token, and will return a 404 if none is provided:

curl https://atlas.oreilly.com/api?auth_token=abcdefg1234567

This token can be revoked via the Atlas UI.

Note

Where to find your API Key

You can find your API key in the "Account Settings" screen, which you access by clicking on your username in the main header.

Builds

Create

POST /api/builds

Create a new build for a specific Atlas project. This will only succeed if the authenticated user is allowed to clone the repository from Atlas and the project has an atlas.json file with at least a list of files to build in order.

Input Parameters

project: Full name of the Atlas repo to build (e.g., runemadsen/Hello-World).

formats: Comma-separated list of formats to build. Possible options are pdf, epub, mobi, html and atlas.

branch: Name of the branch to build. If this is not specified, master will be used. This is useful for building older versions, or managing multiple concurrent versions of a project.

A successful response does not mean that the build finished. You will need to manually check the build_url to know when each of the formats in the build succeeded. There are 4 different states that a build format can return.

Response: Queued

A queued response means that the build is waiting in the queue to be performed.

{
  "build_url" : "https://atlas.oreilly.com/api/builds/1",
  "status" : [
    {
      "format" : "pdf",
      "status" : "queued"
    }
  ]
}

Response: Working

A working response means that the build is currently being performed.

{
  "build_url" : "https://atlas.oreilly.com/api/builds/1",
  "status" : [
    {
      "format" : "pdf",
      "status" : "working"
    }
  ]
}

Response: Completed

A completed response means that the build successfully completed. You can then grab the file from the download_url. If the build succeeded with warning, you can read those warnings in the message property.

{
  "build_url" : "https://atlas.oreilly.com/api/builds/1",
  "status" : [
    {
      "format" : "pdf",
      "status" : "completed",
      "download_url" : "http//www.something.com/something.pdf",
      "message" : "a potential warning"
    }
  ]
}

Response: Failed

A failed response means that the build failed. Details about the error message are in the message property of the response.

{
  "build_url" : "https://atlas.oreilly.com/api/builds/1",
  "status" : [
    {
      "format" : "pdf",
      "status" : "failed",
      "message" : "This is an error message"
    }
  ]
}

Atlas CLI Packages

We offer two different command-line packages for interacting with the Atlas API: one in Ruby and one in Go.

Atlas API Ruby Gem

Gem to interact with the O'Reilly Atlas API. Requires Ruby >=1.9.

Installing

Install this gem by running:

$ gem install atlas-api

Command Line Script

You can build a specific project by calling the atlas build command line:

$ atlas build ATLAS_TOKEN PROJECT FORMATS BRANCH

A real world example of this would look something like this:

$ atlas build abcdefg oreillymedia/atlas_book_skeleton pdf,epub,html master

Atlas API Go Binary

A Go-based Atlas API client for building projects and publishing them as a web site.

Note

The Go-based Atlas API client is in an alpha stage of development. Please go here to report issues or questions.

Here's the top-level help:

NAME:
   atlas - OºReilly Atlas command line tool
   
USAGE:
   atlas [global options] command [command options] [arguments...]

VERSION:
   0.0.8-alpha

COMMANDS:
   login    Set your login/API credentials
   whoami   Display your login/API credentials
   info     Display info about your Atlas project based on the git config file
   build    Build a project
   open     Open a site
   publish  Publish a site
   help, h  Shows a list of commands or help for one command

GLOBAL OPTIONS:
   --help, -h       show help
   --version, -v    print the version

Installation

  • Download the latest release for your OS architecture
  • Put the file on your main path and rename it to atlas
  • Run chmod + x on it

A packager will be available in a future update.

Usage

With this command, you can do things like this:

  • atlas build -p odewahn/dds-field-guide --html
  • atlas build -p odewahn/dds-field-guide --pdf --epub
  • atlas publish -p odewahn/dds-field-guide --public
  • atlas open -p odewahn/dds-field-guide --public

If you omit the -p flag, the CLI will see if it can find a project name from the remotes defined in your git config. So, if you're in your project's home directory, you can just do this:

  • atlas build --html
  • atlas publish --public
  • atlas open --public
Note

The publish and open capabilities are in a very early stage of development and may not apply to your project.