auspice

<!DOCTYPE html><html lang="en"><head><meta charSet="utf-8"/><meta http-equiv="X-UA-Compatible" content="IE=edge"/><title>Auspice Server API · Auspice</title><meta name="viewport" content="width=device-width"/><meta name="generator" content="Docusaurus"/><meta name="description" content="<blockquote> <p>This API is largely based off the interface used by nextstrain.</p> </blockquote> "/><meta name="docsearch:language" content="en"/><meta property="og:title" content="Auspice Server API · Auspice"/><meta property="og:type" content="website"/><meta property="og:url" content="https://nextstrain.github.io/auspice/"/><meta property="og:description" content="<blockquote> <p>This API is largely based off the interface used by nextstrain.</p> </blockquote> "/><meta property="og:image" content="https://nextstrain.github.io/auspice/img/icon.svg"/><meta name="twitter:card" content="summary"/><meta name="twitter:image" content="https://nextstrain.github.io/auspice/img/icon.svg"/><link rel="shortcut icon" href="/auspice/img/favicon.ico"/><link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/styles/solarized-dark.min.css"/><script type="text/javascript" src="https://buttons.github.io/buttons.js"></script><link rel="stylesheet" href="/auspice/css/main.css"/><script src="/auspice/js/codetabs.js"></script></head><body class="sideNavVisible separateOnPageNav"><div class="fixedHeaderContainer"><div class="headerWrapper wrapper"><header><a href="/auspice/"><img class="logo" src="/auspice/img/logo-light.svg" alt="Auspice"/><h2 class="headerTitleWithLogo">Auspice</h2></a><div class="navigationWrapper navigationSlider"><nav class="slidingNav"><ul class="nav-site nav-site-internal"><li class="siteNavGroupActive"><a href="/auspice/overview" target="_self">Docs</a></li></ul></nav></div></header></div></div><div class="navPusher"><div class="docMainWrapper wrapper"><div class="container docsNavContainer" id="docsNav"><nav class="toc"><div class="toggleNav"><section class="navWrapper wrapper"><div class="navBreadcrumb wrapper"><div class="navToggle" id="navToggler"><i></i></div><h2><i>›</i><span>Customisations</span></h2><div class="tocToggler" id="tocToggler"><i class="icon-toc"></i></div></div><div class="navGroups"><div class="navGroup"><h3 class="navGroupCategoryTitle">Introduction</h3><ul class=""><li class="navListItem"><a class="navItem" href="/auspice/overview">Overview</a></li><li class="navListItem"><a class="navItem" href="/auspice/installation">Installing auspice</a></li><li class="navListItem"><a class="navItem" href="/auspice/inputs">Input file formats</a></li></ul></div><div class="navGroup"><h3 class="navGroupCategoryTitle">Customisations</h3><ul class=""><li class="navListItem"><a class="navItem" href="/auspice/customisations/introduction">Extending Auspice</a></li><div class="navGroup subNavGroup"><h4 class="navGroupSubcategoryTitle">Customising the Client</h4><ul><li class="navListItem"><a class="navItem" href="/auspice/customisations/client/componentInterfaces">Injecting custom components</a></li><li class="navListItem"><a class="navItem" href="/auspice/customisations/client/sidebarTheme">Sidebar theming</a></li></ul></div><div class="navGroup subNavGroup"><h4 class="navGroupSubcategoryTitle">Customising the Server</h4><ul><li class="navListItem navListItemActive"><a class="navItem" href="/auspice/customisations/server/charonAPI">Auspice Server API</a></li><li class="navListItem"><a class="navItem" href="/auspice/customisations/server/serverless">Deploying auspice without a server</a></li></ul></div><li class="navListItem"><a class="navItem" href="/auspice/customisations/authentication">Authentication</a></li></ul></div><div class="navGroup"><h3 class="navGroupCategoryTitle">Tutorial</h3><ul class=""><li class="navListItem"><a class="navItem" href="/auspice/tutorial/overview">Auspice functionality</a></li></ul></div></div></section></div><script> var coll = document.getElementsByClassName('collapsible'); var checkActiveCategory = true; for (var i = 0; i < coll.length; i++) { var links = coll[i].nextElementSibling.getElementsByTagName('*'); if (checkActiveCategory){ for (var j = 0; j < links.length; j++) { if (links[j].classList.contains('navListItemActive')){ coll[i].nextElementSibling.classList.toggle('hide'); coll[i].childNodes[1].classList.toggle('rotate'); checkActiveCategory = false; break; } } } coll[i].addEventListener('click', function() { var arrow = this.childNodes[1]; arrow.classList.toggle('rotate'); var content = this.nextElementSibling; content.classList.toggle('hide'); }); } document.addEventListener('DOMContentLoaded', function() { createToggler('#navToggler', '#docsNav', 'docsSliderActive'); createToggler('#tocToggler', 'body', 'tocActive'); const headings = document.querySelector('.toc-headings'); headings && headings.addEventListener('click', function(event) { if (event.target.tagName === 'A') { document.body.classList.remove('tocActive'); } }, false); function createToggler(togglerSelector, targetSelector, className) { var toggler = document.querySelector(togglerSelector); var target = document.querySelector(targetSelector); if (!toggler) { return; } toggler.onclick = function(event) { event.preventDefault(); target.classList.toggle(className); }; } }); </script></nav></div><div class="container mainContainer"><div class="wrapper"><div class="post"><header class="postHeader"><h1 class="postHeaderTitle">Auspice Server API</h1></header><article><div><span><blockquote> <p>This API is largely based off the interface used by nextstrain. Most probably it will change dramatically over the coming weeks.</p> </blockquote> <p>The client (i.e. the auspice web page) makes requests to a server, for instance requesting a dataset file or requesting a listing of available datasets. The server is referred to as "charon". Currently the server needs to handle three requests (detailed below), which are made to the same domain as the client (this may be changeable in the future).</p> <p>Auspice by itself includes handlers for these requests. These handlers source data from the local filesystem so that running auspice without extensions can view locally available datasets.</p> <p>Customisations of auspice can provide their own handlers, allowing for multiple different use cases. For instance, <strong>auspice.us</strong> (currently located as a subdirectory of auspice) contains handlers to fetch datasets from github repos ("community" builds). The handlers used in <strong>nextstrain.org</strong> fetch datasets from S3 buckets.</p> <h2><a class="anchor" aria-hidden="true" id="where-are-these-handlers-used"></a><a href="#where-are-these-handlers-used" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Where are these "handlers" used?</h2> <p>During development of auspice, the dev-server needs access to these handlers in order to make process requests. Building of the auspice client (<code>auspice build ...</code>) doesn't need to know about these handlers, as the client will simply make requests to the API detailed below. (Currently this is different for serverless builds, see <a href="https://github.com/blab/ZEBOV">github.com/blab/ZEBOV</a> for an example). Serving the auspice client (<code>auspice view ...</code>), or whatever custom server implementation you design, will need to use these handlers.</p> <h2><a class="anchor" aria-hidden="true" id="providing-these-handlers-to-auspice-build-and-auspice-view"></a><a href="#providing-these-handlers-to-auspice-build-and-auspice-view" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Providing these handlers to <code>auspice build</code> and <code>auspice view</code></h2> <p>The handlers should be defined in a javascript file provided to those commands via the <code>--handlers</code> argument. This file should export three functions via:</p> <pre><code class="hljs css language-js"><span class="hljs-built_in">module</span>.exports = { getAvailable, getDataset, getNarrative }; </code></pre> <p>Here's a pseudocode example of one of these functions.</p> <pre><code class="hljs css language-js"><span class="hljs-keyword">const</span> getAvailable = <span class="hljs-function">(<span class="hljs-params">req, res</span>) =></span> { <span class="hljs-keyword">try</span> { <span class="hljs-comment">/* collect available data */</span> res.json(data); } <span class="hljs-keyword">catch</span> (err) { res.statusMessage = <span class="hljs-string">`error message to display in client`</span>; <span class="hljs-built_in">console</span>.log(res.statusMessage); <span class="hljs-comment">/* printed by the server */</span> <span class="hljs-keyword">return</span> res.status(<span class="hljs-number">500</span>).end(); } }; </code></pre> <h1><a class="anchor" aria-hidden="true" id="api-description"></a><a href="#api-description" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>API description</h1> <p>Currently the client makes three requests:</p> <ul> <li><code>/charon/getAvailable</code> -- return a list of available datasets and narratives</li> <li><code>/charon/getDataset</code> -- return the requested dataset</li> <li><code>/charon/getNarrative</code> -- return the requested narrative</li> </ul> <p>You can choose to handle these in your own server, or provide handlers to the auspice (dev-)server which are called whenever these requests are received (see above).</p> <h2><a class="anchor" aria-hidden="true" id="get-available-datasets-charon-getavailable"></a><a href="#get-available-datasets-charon-getavailable" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>get available datasets: <code>/charon/getAvailable</code></h2> <p>Query arguments:</p> <ul> <li><code>prefix</code> (optional) - the pathname of the requesting page in auspice.</li> </ul> <p>Response shape:</p> <pre><code class="hljs css language-json">{ <span class="hljs-attr">"datasets"</span>: [ {<span class="hljs-attr">"request"</span>: <span class="hljs-string">"URL of a dataset. Will become the prefix in a getDataset request"</span>}, ... ], <span class="hljs-attr">"narratives"</span>: [ {<span class="hljs-attr">"request"</span>: <span class="hljs-string">"URL of a narrative. Will become the prefix in a getNarrative request"</span>}, ... ] } </code></pre> <h2><a class="anchor" aria-hidden="true" id="get-a-dataset-charon-getdataset"></a><a href="#get-a-dataset-charon-getdataset" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>get a dataset: <code>/charon/getDataset</code></h2> <p>Query arguments:</p> <ul> <li><code>prefix</code> (required) - the pathname of the requesting page in auspice. Use this to determine which dataset to return.</li> <li><code>deprecatedSecondTree</code> (optional) - deprecated.</li> <li><code>type</code> (optional) -- if specified, then the request is for an additional file (e.g. "tip-frequencies"), not the main dataset.</li> </ul> <p>Response shape:</p> <blockquote> <p>This needs to be updated to schema 2.0. These docs should point to the schema definitions (currently in the augur repo).</p> </blockquote> <p>The current main dataset response shape is:</p> <pre><code class="hljs css language-json">{ <span class="hljs-attr">"meta"</span>: <span class="hljs-string">"the schema 1.0 metadata json object"</span>, <span class="hljs-attr">"tree"</span>: <span class="hljs-string">"the schema 1.0 tree json object"</span>, <span class="hljs-attr">"_source"</span>: <span class="hljs-string">"the source (e.g. live, staging, github). Only used by the sidebar dataset selector"</span>, <span class="hljs-attr">"_url"</span>: <span class="hljs-string">"the URL to which auspice should update. Allows flu to redirect silently to flu/seasonal/..."</span> } </code></pre> <h2><a class="anchor" aria-hidden="true" id="get-a-narrative-charon-getnarrative"></a><a href="#get-a-narrative-charon-getnarrative" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>get a narrative: <code>/charon/getNarrative</code></h2> <blockquote> <p>to do</p> </blockquote> </span></div></article></div><div class="docLastUpdate"><em>Last updated on 1/15/2019</em></div><div class="docs-prevnext"><a class="docs-prev button" href="/auspice/customisations/client/sidebarTheme"><span class="arrow-prev">← </span><span>Sidebar theming</span></a><a class="docs-next button" href="/auspice/customisations/server/serverless"><span>Deploying auspice without a server</span><span class="arrow-next"> →</span></a></div></div></div><nav class="onPageNav"><ul class="toc-headings"><li><a href="#where-are-these-handlers-used">Where are these "handlers" used?</a></li><li><a href="#providing-these-handlers-to-auspice-build-and-auspice-view">Providing these handlers to <code>auspice build</code> and <code>auspice view</code></a></li><li><a href="#get-available-datasets-charon-getavailable">get available datasets: <code>/charon/getAvailable</code></a></li><li><a href="#get-a-dataset-charon-getdataset">get a dataset: <code>/charon/getDataset</code></a></li><li><a href="#get-a-narrative-charon-getnarrative">get a narrative: <code>/charon/getNarrative</code></a></li></ul></nav></div><footer class="nav-footer" id="footer"><section class="sitemap"><div><img src="/auspice/img/logo-light.svg" alt="Auspice" width="66" height="58"/></div><div><h5>Docs</h5><a href="/auspice/">Splash Page</a><a href="/auspice/overview">Overview</a></div><div><h5>Links</h5><a href="https://github.com/nextstrain/auspice">GitHub</a><a href="https://www.npmjs.com/package/auspice">NPM</a><a href="https://nextstrain.org">Nextstrain</a></div><div><h5>Contact</h5><a href="mailto:hello@nextstrain.org">email</a><a href="https://twitter.com/hamesjadfield">twitter</a></div></section><section class="copyright">If you use auspice, please cite <a href="https://doi.org/10.1093/bioinformatics/bty407">Hadfield et al., 2018</a></section><section class="copyright">Copyright © 2014-2019 Richard Neher & Trevor Bedford</section></footer></div></body></html>