epubjs
Version:
Render ePub documents in the browser, across many devices
158 lines (117 loc) • 6.66 kB
HTML
<html xmlns:epub="http://www.idpf.org/2007/ops" xmlns="http://www.w3.org/1999/xhtml"><head><title>O’Reilly Atlas API</title><link rel="stylesheet" type="text/css" href="epub.css"/></head><body data-type="book"><section data-type="chapter" epub:type="chapter" data-pdf-bookmark="Chapter 9. O’Reilly Atlas API"><div class="chapter" id="atlas-api">
<h1><span class="label">Chapter 9. </span>O’Reilly Atlas API</h1>
<p>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.</p>
<section data-type="sect1" data-pdf-bookmark="Authentication"><div class="sect1" id="idm48160">
<h1>Authentication</h1>
<p>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 requires an auth_token, and will return a 404 if none is provided.</p>
<p><code>curl https://atlas.oreilly.com/api?auth_token=abcdefg1234567 </code></p>
<p>This token can be revoked via the Atlas UI.</p>
</div></section>
<section data-type="sect1" data-pdf-bookmark="Builds"><div class="sect1" id="idm45296">
<h1>Builds</h1>
<section data-type="sect2" data-pdf-bookmark="Create"><div class="sect2" id="idm44288">
<h2>Create</h2>
<p><code>POST /api/builds</code></p>
<p>Create a new build for a specific GitHub project. This will only succeed if the authenticated user is allowed to clone the repository from GitHub, and the project has an <code>atlas.json</code> file with at least a list of files to build in order.</p>
<section data-type="sect3" data-pdf-bookmark="Input Parameters"><div class="sect3" id="idm41376">
<h3>Input Parameters</h3>
<p><strong>project</strong>: Full name of the GitHub repo to build (e.g. <code>runemadsen/Hello-World</code>)</p>
<p><strong>formats</strong>: Comma-separated list of formats to build. Possible options are <code>pdf</code>, <code>epub</code>, <code>mobi</code>, <code>html</code> and <code>atlas</code>.</p>
<p><strong>branch</strong>: Name of the branch to build. If this is not specified, <code>master</code> will be used. This is useful for building older versions, or managing multiple concurrent versions of a project.</p>
<p><strong>pingback_url</strong>: A valid URL for the API to ping when a build succeeds or fails. This method is prefered over manually pinging the <code>build_url</code> for updates. Note that the <code>pingback_url</code> will be called once per format. If you’re building your project as <code>pdf</code> and <code>epub</code>, the <code>pingback_url</code> will be called twice.</p>
<p>A <strong>successful</strong> response does not mean that the build finished. You will need to either provide a <code>pingback_url</code> or manually check the <code>build_url</code> to know when each of the formats in the build succeeded. There are 4 different states that a build format can return.</p>
<p>A <code>queued</code> response means that the build is waiting in the queue to be performed.</p>
</div></section>
<section data-type="sect3" data-pdf-bookmark="Response: Queued"><div class="sect3" id="idm28592">
<h3>Response: Queued</h3>
<pre data-original-title="" title="">
{
"build_url" : "https://atlas.oreilly.com/api/builds/1",
"status" : [
{
"format" : "pdf",
"status" : "queued"
}
]
}
</pre>
<p>A <code>working</code> response means that the build is currently being performed.</p>
</div></section>
<section data-type="sect3" data-pdf-bookmark="Response: Working"><div class="sect3" id="idm25264">
<h3>Response: Working</h3>
<pre data-original-title="" title="">
{
"build_url" : "https://atlas.oreilly.com/api/builds/1",
"status" : [
{
"format" : "pdf",
"status" : "working"
}
]
}
</pre>
<p>A <code>completed</code> response means that the build successfully completed. You can then grab the file from the <code>download_url</code>. Note that the build files will be deleted a week after the build succeeds. If you want to persist the build files longer than that, you will need to do download the files and upload them to a persistent file storage. If the build succeeded with warning, you can read those warnings in the <code>message</code> property.</p>
</div></section>
<section data-type="sect3" data-pdf-bookmark="Response: Completed"><div class="sect3" id="idm20784">
<h3>Response: Completed</h3>
<pre data-original-title="" title="">
{
"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"
}
]
}
</pre>
<p>A <code>failed</code> response means that the build failed. Details about the error message is in the <code>message</code> property of the response.</p>
</div></section>
<section data-type="sect3" data-pdf-bookmark="Response: Failed"><div class="sect3" id="idm16976">
<h3>Response: Failed</h3>
<pre data-original-title="" title="">
{
"build_url" : "https://atlas.oreilly.com/api/builds/1",
"status" : [
{
"format" : "pdf",
"status" : "failed",
"message" : "This is an error message"
}
]
}
</pre>
</div></section>
</div></section>
</div></section>
<section data-type="sect1" data-pdf-bookmark="Atlas API Ruby Gem"><div class="sect1" id="atlas-gem">
<h1>Atlas API Ruby Gem</h1>
<p>Gem to interact with the O’Reilly Media Atlas API.</p>
<section data-type="sect2" data-pdf-bookmark="Installing"><div class="sect2" id="idm12544">
<h2>Installing</h2>
<p>Install this gem by running:</p>
<pre data-original-title="" title="">
$ gem install atlas-api
</pre>
</div></section>
<section data-type="sect2" data-pdf-bookmark="Command Line Script"><div class="sect2" id="idp1202992">
<h2>Command Line Script</h2>
<p>You can build a specific project by calling the `atlas build` command line:</p>
<pre data-original-title="" title="">
$ atlas build ATLAS_TOKEN PROJECT FORMATS BRANCH
</pre>
<div data-type="note" epub:type="note">
<h1>Where to find your API Key</h1>
<p>You can find your API key in the “Settings” screen, which you access by clicking your username in the main header.</p>
<p><img class="icontentsimagesfind_api_keypng" src="assets/find_api_key.png"/></p>
</div>
<p>A real world example of this would look something like this:</p>
<pre>
$ atlas build abcdefg oreillymedia/atlas_book_skeleton pdf,epub,html master
</pre>
</div></section>
</div></section>
</div></section></body></html>