---
layout      : 'default'
css         : 'api'

title       : 'API'
description : 'API allows UI elements to send events to the server'
type        : 'UI Behavior'
---

<script src="/javascript/library/sinon.js"></script>
<script src="/javascript/api.js"></script>

<%- @partial('header', { tabs: 'behavior' }) %>

<div class="main container">
  <div class="ui active tab" data-tab="overview">
    <div class="ui two column stackable grid">
      <div class="row">
        <div class="sixteen wide column">
          <p>Semantic API helps attach server events to UI elements. There a few key features which make API more useful then jQuery AJAX or and simpler than MVC patterns.</p>
        </div>
      </div>
      <div class="row">
        <div class="column">
          <div class="content">
            <div class="ui header"><i class="green check icon"></i>Already Knows Your UI</div>
            <p>Attach an API event to an input, by default, it will occur <code>oninput</code>. Attach an API event to a button, <code>onclick</code>. State management is built in: rate throttling, UI state changes like active, loading, disabled, min/max request lengths and more.</p>
          </div>
        </div>
        <div class="column">
          <div class="content">
            <div class="ui header"><i class="green check icon"></i>Deal with resources not URLs</div>
            <p> Store all your API endpoints as templated URLs in one place inside your code, and then trigger named <em>human readable</em> API actions like <code>'get tweet'</code>. </p>
            <div class="ui button">See example</div>
          </div>
        </div>
      </div>
    <div class="row">
        <div class="column">
          <div class="content">
            <div class="ui header"><i class="green check icon"></i>URL Templating built In</div>
            <p>API is made for REST. Store your API endpoints with url variables that are replaced at run-time.</p>
          </div>
        </div>
        <div class="column">
          <div class="content">
            <div class="ui header"><i class="green check icon"></i>Server Traces For Humans</div>
            <p>View your API request as it occurs, get errors if required url variables are missing, and other useful performance metrics.</p>
          </div>
        </div>
      </div>
    </div>
  </div>

  <div class="ui tab" data-tab="usage">
    <div class="fixed column">
      <div class="content">
        <h2 class="ui header">Demo</h2>
        <div class="ui items">
          <div class="item">
            <div class="image">
              <img src="/images/demo/highres3.jpg">
            </div>
            <div class="content">
              <div class="ui fluid adopt toggle button" data-id="5209">
                <i class="checkmark icon"></i>
                <span class="text">Adopt</span>
              </div>
            </div>
          </div>
        </div>
      </div>
    </div>
    <div class="examples">

      <h3 class="ui header">1. Define Your API</h3>
      <p><b>API</b> works best when using a named list of endpoints. This means you can maintain all of your website's API endpoints in a single location, without having to update them across the site.</p>
      <p>To do this you must include a list of named endpoints before calling <code>$.api</code> on any page. The easiest way to do this is to have it available in a stand-alone configuration file.</p>

      <p>For the sake of this example we will use Github's public API as an example</p>
      <div class="evaluated code">
        /* "Config.js" - Define API endpoints once globally */
        $.fn.api.settings.api = {
          'follow user' : '/api/follow/{$id}',
          'user info'   : '/api/user/{$id}'
        };
      </div>
      <div class="code" data-type="html">
        <!-- Include on any page using API !-->
        <script src="/config.js"></script>
      </div>

      <h3 class="ui header">2. Attach an API event to an element</h3>

      <p>Any element can have an API action attached, by default the action will occur on the most relevant event for the type of element. For example a button will use on <code>click</code> or an input <code>oninputchange</code></p>

      <div class="evaluated code">
      $('.adopt.button')
        .api({
          action: 'follow user'
        })
      ;
      </div>

      <h3 class="ui header">2. Specify state changes to text or appearance (optional)</h3>
      <p>API couples well with <a href="#">ui state</a>, a component used for managing text state and class names of elements.</p>
      <p>State will automatically apply the class <code>active</code> on API success, and update any text nodes with new values specified. This example updates the text of a follow button to "following" when the API action is successful, after flashing the text success.</p>
      <div class="evaluated code">
      $('.adopt.button')
        .state({
          text: {
            inactive   : 'Adopt',
            active     : 'Adopted',
            deactivate : 'Undo',
            flash      : 'Success'
          }
        })
      ;
      </div>

      <h3 class="ui header">4. Make sure metadata is set for an element before event occurs</h3>

      <p>When an API action occurs, templated url data is replaced with data you specify to be sent to the server.</p>
      <div class="code" data-type="html">
        <div class="ui adopt button" data-id="5209"></div>
      </div>
      <div class="ui horizontal divider">Or</div>
      <p>Alternatively you can modify the data before sending to server</p>
      <div class="code">
      $('.adopt.button')
        .api('setting', 'beforeSend', function(settings) {
          settings.urlData.id = 5209;
          return settings;
        })
      ;
      </div>
    </div>

  </div>

  <div class="ui tab" data-tab="examples">

    <div class="no example">
      <h4 class="ui header">Overlay</h4>
      <p>A api can overlay page content instead of pushing it to the side</p>
      <div class="code" data-demo="true">
      $('.overlay.api')
        .api({
          overlay: true
        })
        .api('toggle')
      ;
      </div>
    </div>

  </div>

  <div class="ui tab" data-tab="settings">

    <h3 class="ui header">
      API Settings
      <div class="sub header">Form settings modify the api behavior</div>
    </h3>
    <table class="ui celled sortable definition table segment">
      <thead>
        <th>Setting</th>
        <th class="four wide">Default</th>
        <th>Description</th>
      </thead>
      <tbody>
        <tr>
          <td>overlay</td>
          <td>false</td>
          <td>Whether api should overlay page instead of pushing page to the side</td>
        </tr>
        <tr>
          <td>exclusive</td>
          <td>true</td>
          <td>Whether multiple apis can be open at once</td>
        </tr>
        <tr>
          <td>useCSS</td>
          <td>true</td>
          <td>Whether to use css animations or fallback javascript animations</td>
        </tr>
        <tr>
          <td>duration</td>
          <td>300</td>
          <td>Duration of side bar transition animation</td>
        </tr>
      </tbody>
    </table>

    <div class="ui horizontal section icon divider"><i class="icon setting"></i></div>
    <h4 class="ui header">Callbacks</h4>
    <p>Callbacks specify a function to occur after a specific behavior.</p>

    <table class="ui celled sortable definition table segment">
      <thead>
        <th class="four wide">Setting</th>
        <th>Context</th>
        <th>Description</th>
      </thead>
      <tbody>
        <tr>
          <td>onShow</td>
          <td>API</td>
          <td>Is called when a api is shown.</td>
        </tr>
        <tr>
          <td>onHide</td>
          <td>API</td>
          <td>Is called when a api is hidden.</td>
        </tr>
        <tr>
          <td>onChange</td>
          <td>API</td>
          <td>Is called after a api changes visibility</td>
        </tr>
      </tbody>
    </table>

    <div class="ui horizontal divider"><i class="icon setting"></i></div>

    <h3 class="ui header">
      DOM Settings
      <div class="sub header">DOM settings specify how this module should interface with the DOM</div>
    </h3>
    <table class="ui celled definition table segment">
      <thead>
        <th>Setting</th>
        <th class="six wide">Default</th>
        <th>Description</th>
      </thead>
      <tbody>
        <tr>
          <td>namespace</td>
          <td>api</td>
          <td>Event namespace. Makes sure module teardown does not effect other events attached to an element.</td>
        </tr>
        <tr>
          <td>className</td>
          <td>
            <div class="code">
      className: {
        active : 'active',
        pushed : 'pushed',
        top    : 'top',
        left   : 'left',
        right  : 'right',
        bottom : 'bottom'
      }
            </div>
          </td>
          <td>Class names used to attach style to state</td>
        </tr>
      </tbody>
    </table>

    <div class="ui horizontal divider"><i class="icon setting"></i></div>

    <h3 class="ui header">
      Debug Settings
      <div class="sub header">Debug settings controls debug output to the console</div>
    </h3>

    <table class="ui celled sortable definition table segment">
      <thead>
        <th>Setting</th>
        <th class="four wide">Default</th>
        <th>Description</th>
      </thead>
      <tbody>
        <tr>
          <td>name</td>
          <td>API</td>
          <td>Name used in debug logs</td>
        </tr>
        <tr>
          <td>debug</td>
          <td>True</td>
          <td>Provides standard debug output to console</td>
        </tr>
        <tr>
          <td>performance</td>
          <td>True</td>
          <td>Provides standard debug output to console</td>
        </tr>
        <tr>
          <td>verbose</td>
          <td>True</td>
          <td>Provides ancillary debug output to console</td>
        </tr>
        <tr>
          <td>errors</td>
          <td colspan="2">
            <div class="code">
      error   : {
        method   : 'The method you called is not defined.',
        notFound : 'There were no elements that matched the specified selector'
      }
            </div>
          </td>
        </tr>
      </tbody>
    </table>
  </div>

</div>
</body>
</html>