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.