<!DOCTYPE html>
  
  
  
  
   <html class="no-js"> 

  <head lang="en-us">
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width,user-scalable=no,initial-scale=1,maximum-scale=1">
    <meta http-equiv="X-UA-Compatible" content="IE=10" />
    <title>The Javascript Client - Sondra Documentation</title>
    <meta name="generator" content="Hugo 0.17" />

    
    <meta name="description" content="A framework for creating rich APIs with Python and RethinkDB.">
    
    <link rel="canonical" href="https://jeffersonheard.github.io/sondra/topical-guides/javascript/">
    
    <meta name="author" content="Jefferson Heard">
    

    <meta property="og:url" content="https://jeffersonheard.github.io/sondra/topical-guides/javascript/">
    <meta property="og:title" content="Sondra Documentation">
    <meta property="og:image" content="https://jeffersonheard.github.io/sondra//img/sondra.svg">
    <meta name="apple-mobile-web-app-title" content="Sondra Documentation">
    <meta name="apple-mobile-web-app-capable" content="yes">
    <meta name="apple-mobile-web-app-status-bar-style" content="black-translucent">

    <link rel="shortcut icon" type="image/x-icon" href="https://jeffersonheard.github.io/sondra/images/favicon.ico">
    <link rel="icon" type="image/x-icon" href="https://jeffersonheard.github.io/sondra/images/favicon.ico">

    <style>
      @font-face {
        font-family: 'Icon';
        src: url('https://jeffersonheard.github.io/sondra/fonts/icon.eot?52m981');
        src: url('https://jeffersonheard.github.io/sondra/fonts/icon.eot?#iefix52m981')
               format('embedded-opentype'),
             url('https://jeffersonheard.github.io/sondra/fonts/icon.woff?52m981')
               format('woff'),
             url('https://jeffersonheard.github.io/sondra/fonts/icon.ttf?52m981')
               format('truetype'),
             url('https://jeffersonheard.github.io/sondra/fonts/icon.svg?52m981#icon')
               format('svg');
        font-weight: normal;
        font-style: normal;
      }
    </style>
    <link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.6.0/styles/default.min.css">
    <script src="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.6.0/highlight.min.js"></script>
    <script>hljs.initHighlightingOnLoad();</script>

    <link rel="stylesheet" href="https://jeffersonheard.github.io/sondra/stylesheets/application.css">
    <link rel="stylesheet" href="https://jeffersonheard.github.io/sondra/stylesheets/temporary.css">
    <link rel="stylesheet" href="https://jeffersonheard.github.io/sondra/stylesheets/palettes.css">
    <link rel="stylesheet" href="https://jeffersonheard.github.io/sondra/stylesheets/highlight/highlight.css">

    
    
    
    <link rel="stylesheet" href="//fonts.googleapis.com/css?family=Ubuntu:400,700|Ubuntu&#43;Mono">
    <style>
      body, input {
        font-family: 'Ubuntu', Helvetica, Arial, sans-serif;
      }
      pre, code {
        font-family: 'Ubuntu Mono', 'Courier New', 'Courier', monospace;
      }
    </style>

    
    <script src="https://jeffersonheard.github.io/sondra/javascripts/modernizr.js"></script>

    

  </head>
  <body class="palette-primary-brown palette-accent-teal">



	
	


<div class="backdrop">
	<div class="backdrop-paper"></div>
</div>

<input class="toggle" type="checkbox" id="toggle-drawer">
<input class="toggle" type="checkbox" id="toggle-search">
<label class="toggle-button overlay" for="toggle-drawer"></label>

<header class="header">
	<nav aria-label="Header">
  <div class="bar default">
    <div class="button button-menu" role="button" aria-label="Menu">
      <label class="toggle-button icon icon-menu" for="toggle-drawer">
        <span></span>
      </label>
    </div>
    <div class="stretch">
      <div class="title">
        The Javascript Client
      </div>
    </div>

    
    <div class="button button-twitter" role="button" aria-label="Twitter">
       <a href="https://twitter.com/jeffersonheard" title="@jeffersonheard on Twitter" target="_blank" class="toggle-button icon icon-twitter"></a>
    </div>
    

    
    <div class="button button-github" role="button" aria-label="GitHub">
      <a href="https://github.com/jeffersonheard" title="@jeffersonheard on GitHub" target="_blank" class="toggle-button icon icon-github"></a>
    </div>
    
    
        
  </div>
  <div class="bar search">
    <div class="button button-close" role="button" aria-label="Close">
      <label class="toggle-button icon icon-back" for="toggle-search"></label>
    </div>
    <div class="stretch">
      <div class="field">
        <input class="query" type="text" placeholder="Search" autocapitalize="off" autocorrect="off" autocomplete="off" spellcheck>
      </div>
    </div>
    <div class="button button-reset" role="button" aria-label="Search">
      <button class="toggle-button icon icon-close" id="reset-search"></button>
    </div>
  </div>
</nav>
</header>

<main class="main">
	<div class="drawer">
		<nav aria-label="Navigation">
  <a href="https://github.com/jeffersonheard/sondra" class="project">
    <div class="banner">
      
        <div class="logo">
          <img src="https://jeffersonheard.github.io/sondra//img/sondra.svg">
        </div>
      
      <div class="name">
        <strong>Sondra Documentation <span class="version">1.0.0</span></strong>
        
          <br>
          jeffersonheard/sondra
        
      </div>
    </div>
  </a>

  <div class="scrollable">
    <div class="wrapper">
      
        <ul class="repo">
          <li class="repo-download">
            <a href="https://github.com/jeffersonheard/sondra/archive/master.zip" target="_blank" title="Download" data-action="download">
              <i class="icon icon-download"></i> Download
            </a>
          </li>
          <li class="repo-stars">
            <a href="https://github.com/jeffersonheard/sondra/stargazers" target="_blank" title="Stargazers" data-action="star">
              <i class="icon icon-star"></i> Stars
              <span class="count">&ndash;</span>
            </a>
          </li>
        </ul>
        <hr>
      

      <div class="toc">
        
        <ul>
          




<li>
  
    



<a  title="Introduction" href="https://jeffersonheard.github.io/sondra/">
	
	Introduction
</a>



  
</li>



<li>
  
    <span class="section">Tutorial</span>
    <ul>
      
        
        



<a  title="Your first Sondra API" href="https://jeffersonheard.github.io/sondra/basics/tutorial-1/">
	
	Your first Sondra API
</a>



      
        
        



<a  title="Expose it to the Web" href="https://jeffersonheard.github.io/sondra/basics/tutorial-2/">
	
	Expose it to the Web
</a>



      
        
        



<a  title="Accessing Schemas" href="https://jeffersonheard.github.io/sondra/basics/tutorial-3/">
	
	Accessing Schemas
</a>



      
        
        



<a  title="Adding and Accessing Data" href="https://jeffersonheard.github.io/sondra/basics/tutorial-4/">
	
	Adding and Accessing Data
</a>



      
    </ul>
  
</li>



<li>
  
    <span class="section">Topical Guides</span>
    <ul>
      
        
        



<a  title="Output Formats" href="https://jeffersonheard.github.io/sondra/extending/output-formats/">
	
	Output Formats
</a>



      
        
        



<a  title="Request Processors" href="https://jeffersonheard.github.io/sondra/extending/request-processors/">
	
	Request Processors
</a>



      
        
        



<a  title="The Flask App" href="https://jeffersonheard.github.io/sondra/topical-guides/flask/">
	
	The Flask App
</a>



      
        
        



<a  title="Value Handlers" href="https://jeffersonheard.github.io/sondra/extending/value-handlers/">
	
	Value Handlers
</a>



      
        
        



<a  title="Working with Applications" href="https://jeffersonheard.github.io/sondra/topical-guides/applications/">
	
	Working with Applications
</a>



      
        
        



<a  title="Collections" href="https://jeffersonheard.github.io/sondra/topical-guides/collections/">
	
	Collections
</a>



      
        
        



<a  title="Documents" href="https://jeffersonheard.github.io/sondra/topical-guides/documents/">
	
	Documents
</a>



      
        
        



<a  title="Exposing Methods" href="https://jeffersonheard.github.io/sondra/topical-guides/methods/">
	
	Exposing Methods
</a>



      
        
        



<a  title="The Javascript Client" href="https://jeffersonheard.github.io/sondra/topical-guides/javascript/">
	
	The Javascript Client
</a>



      
        
        



<a  title="Queries over HTTP/S" href="https://jeffersonheard.github.io/sondra/topical-guides/querying/">
	
	Queries over HTTP/S
</a>



      
        
        



<a  title="QuerySets in Python" href="https://jeffersonheard.github.io/sondra/topical-guides/querysets/">
	
	QuerySets in Python
</a>



      
        
        



<a  title="Suites" href="https://jeffersonheard.github.io/sondra/topical-guides/suites/">
	
	Suites
</a>



      
    </ul>
  
</li>



<li>
  
    <span class="section">Extending</span>
    <ul>
      
        
        



<a  title="Document Processors" href="https://jeffersonheard.github.io/sondra/extending/document-processors/">
	
	Document Processors
</a>



      
    </ul>
  
</li>


        </ul>
        

        
        <hr>
        <span class="section">The author</span>
        
        <ul>
          
          <li>
            <a href="https://twitter.com/jeffersonheard" target="_blank" title="@jeffersonheard on Twitter">
              @jeffersonheard on Twitter
            </a>
          </li>
          

          
          <li>
            <a href="https://github.com/jeffersonheard" target="_blank" title="@jeffersonheard on GitHub">
              @jeffersonheard on GitHub
            </a>
          </li>
          

          
          <li>
            <a href="mailto:jefferson.r.heard@gmail.com" title="Email of jefferson.r.heard@gmail.com">
              Contact via email
            </a>
          </li>
          
        </ul>
        
      </div>
    </div>
  </div>
</nav>

	</div>

	<article class="article">
		<div class="wrapper">
			<h1>The Javascript Client </h1>

			

<p>Sondra does not wrap raw objects unless requested to. Also, GET, POST, PUT, PATCH, and DELETE
metaphors behave as expected. Therefore a simple XMLHttpRequest or a call to the new standard
Fetch API with raw JSON objects that conform to the schema will work just fine.
<a href="https://jeffersonheard.github.io/sondra/basics/tutorial-4">See the tutorial</a> for more information on how these work.</p>

<p>For those who want something more high level, Sondra has a
<a href="https://github.com/jeffersonheard/sondra-client">Javascript client</a>. This client uses ES6 and
Bluebird.js to make a modern, promise-based API for remote communication with a Sondra-based API
server.</p>

<h2 id="client-api">Client API</h2>

<h2 id="example-fetch-a-schema">Example: Fetch a schema</h2>

<pre><code class="language-javascript">import { Sondra, QuerySet } from 'sondra-client';

const api = new Sondra().suite('http', 'localhost', 5000);
const auth = api.app('auth');
const users = auth.collection('users');
const login = auth.method('login');
const jefferson = users.document('jefferson');

users.fetchSchema().then((schema) =&gt; {  // we set the format first to make sure that schema overrides it.
  console.log('schema')    
});
</code></pre>

<h3 id="results">Results</h3>

<p>The resulting schema is quite large. For the purposes of this guide, we have left out much of it.
API (Suite), application, and collection schemas are self describing. Within the suite schema are
references to all the applications under the attribute <code>applications</code>. Within the application schema
are references to all the collections under the attribute <code>collections</code> as well as to
application-wide methods under <code>methods</code>. Within collections are the  document schemas, and these
also contain references to collection-wide methods under the attribute <code>methods</code> and to
document-specific (instance) methods under <code>documentMethods</code>.</p>

<pre><code class="language-javascript">{
  &quot;type&quot;: &quot;object&quot;,
  &quot;properties&quot;: {
    &quot;username&quot;: {
      &quot;type&quot;: &quot;string&quot;,
      &quot;description&quot;: &quot;The user's username&quot;,
      &quot;title&quot;: &quot;Username&quot;
    },
    &quot;email&quot;: {
      &quot;type&quot;: &quot;string&quot;,
      &quot;format&quot;: &quot;email&quot;,
      &quot;description&quot;: &quot;The user's email address&quot;,
      &quot;title&quot;: &quot;Email&quot;,
      &quot;pattern&quot;: &quot;^[^@]+@[^@]+\\.[^@]+$&quot;
    },
     /* ... The actual schema is quite long. */
}
</code></pre>

<h2 id="example-fetch-a-set-of-documents">Example: Fetch a set of documents</h2>

<p>This example retrieves the first page of documents from the API.</p>

<pre><code class="language-javascript">
const api = new Sondra().suite('http', 'localhost', 5000);
const auth = api.app('auth');
const users = auth.collection('users');
const login = auth.method('login');

login.call({body: {username: 'jefferson', password: 'mypassword'}})
  .then((rsp) =&gt; {
    const { _:token } = rsp;
    const todoApp = todo.app('todo-app').auth(token);
    const items = todoApp.collection('items');
    items.call().then((items) =&gt; {
      / ** do something with the item list *//
    });
</code></pre>

<h2 id="example-query-a-collection">Example: Query a collection</h2>

<p>The above example fetches by default the first hundred documents returned by a simple database
query. This is often useful, but more useful is the ability to limit and filter the data. The
following example uses a QuerySet object to limit the data. For more information on querying and
querysets, <a href="querying">see the topical guide on querying</a>.</p>

<pre><code class="language-javascript">
import { Sondra, QuerySet } from 'sondra-client';

const api = new Sondra().suite('http', 'localhost', 5000);
const auth = api.app('auth');
const users = auth.collection('users');
const login = auth.method('login');

login.call({body: {username: 'jefferson', password: 'mypassword'}})
  .then((token) =&gt; Promise.resolve(api.auth(token._)))
  .then((authorizedApi) =&gt; {
    const todoApp = todo.app('todo-app');
    const items = todoApp.collection('items');

    // apply a start and a limit. See sondra.js for a full list of methods supported by QuerySet.
    const q = new QuerySet().start(0).limit(5);  

    items.query(q).call().then((items) =&gt; {
      / ** do something with the item list *//
    });
</code></pre>

<p>The Javascript client is complete, and you can do anything within it that you can with Fetch or
XMLHttpRequest. For more information on the API, see the ESDoc in the repository.</p>


			<aside class="copyright" role="note">
				
				&copy; 2016 Released under the MIT license &ndash;
				
				Documentation built with
				<a href="https://www.gohugo.io" target="_blank">Hugo</a>
				using the
				<a href="http://github.com/digitalcraftsman/hugo-material-docs" target="_blank">Material</a> theme.
			</aside>

			<footer class="footer">
				

<nav class="pagination" aria-label="Footer">
  <div class="previous">
  
      <a href="https://jeffersonheard.github.io/sondra/topical-guides/methods/" title="Exposing Methods">
        <span class="direction">
          Previous
        </span>
        <div class="page">
          <div class="button button-previous" role="button" aria-label="Previous">
            <i class="icon icon-back"></i>
          </div>
          <div class="stretch">
            <div class="title">
              Exposing Methods
            </div>
          </div>
        </div>
      </a>
  
  </div>

  <div class="next">
  
      <a href="https://jeffersonheard.github.io/sondra/extending/" title="Extending">
        <span class="direction">
          Next
        </span>
        <div class="page">
          <div class="stretch">
            <div class="title">
              Extending
            </div>
          </div>
          <div class="button button-next" role="button" aria-label="Next">
            <i class="icon icon-forward"></i>
          </div>
        </div>
      </a>
  
  </div>
</nav>





			</footer>
		</div>
	</article>

	<div class="results" role="status" aria-live="polite">
		<div class="scrollable">
			<div class="wrapper">
				<div class="meta"></div>
				<div class="list"></div>
			</div>
		</div>
	</div>
</main>

    <script>
    
      var base_url = 'https:\/\/jeffersonheard.github.io\/sondra\/';
      var repo_id  = 'jeffersonheard\/sondra';
    
    </script>

    <script src="https://jeffersonheard.github.io/sondra/javascripts/application.js"></script>
    

    <script>
      /* Add headers to scrollspy */
      var headers   = document.getElementsByTagName("h2");
      var scrollspy = document.getElementById('scrollspy');

      if(scrollspy) {
        if(headers.length > 0) {
          for(var i = 0; i < headers.length; i++) {
            var li = document.createElement("li");
            li.setAttribute("class", "anchor");

            var a  = document.createElement("a");
            a.setAttribute("href", "#" + headers[i].id);
            a.setAttribute("title", headers[i].innerHTML);
            a.innerHTML = headers[i].innerHTML;
            
            li.appendChild(a)
            scrollspy.appendChild(li);
          }
        } else {
          scrollspy.parentElement.removeChild(scrollspy)
        }
        

        /* Add permanent link next to the headers */
        var headers = document.querySelectorAll("h1, h2, h3, h4, h5, h6");

        for(var i = 0; i < headers.length; i++) {
            var a = document.createElement("a");
            a.setAttribute("class", "headerlink");
            a.setAttribute("href", "#" + headers[i].id);
            a.setAttribute("title", "Permanent link")
            a.innerHTML = "https://jeffersonheard.github.io/sondra/";
            headers[i].appendChild(a);
        }
      }
    </script>

    
      <script>
        (function(i,s,o,g,r,a,m){
          i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){(i[r].q=i[r].q||
          []).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
          m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;
          m.parentNode.insertBefore(a,m)
        })(window, document,
          'script', '//www.google-analytics.com/analytics.js', 'ga');
         
        ga('create', 'UA-68674847-2', 'auto');
        ga('set', 'anonymizeIp', true);
        ga('send', 'pageview');
         
        var buttons = document.querySelectorAll('a');
        Array.prototype.map.call(buttons, function(item) {
          if (item.host != document.location.host) {
            item.addEventListener('click', function() {
              var action = item.getAttribute('data-action') || 'follow';
              ga('send', 'event', 'outbound', action, item.href);
            });
          }
        });
         
        var query = document.querySelector('.query');
        query.addEventListener('blur', function() {
          if (this.value) {
            var path = document.location.pathname;
            ga('send', 'pageview', path + '?q=' + this.value);
          }
        });
      </script>
    

    <script src="//gohugo.io/js/highlight.pack.js"></script>
    <script>hljs.initHighlightingOnLoad();</script>
  </body>
</html>
