SemanSemantic-UItic-UI/server/documents/modules/api.html.eco

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

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

<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 raised segment">
      <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 dividing header"><i class="green check icon"></i>Tie API Events to UI</div>
              <p>API is built specifically to interact with user interfaces, allowing features like, ui state management, rate throttling, single-request limits, minimum request time, and other features specifically designed to make server loads more human-friendly.</p>
            </div>
          </div>
          <div class="column">
            <div class="content">
              <div class="ui dividing header"><i class="green check icon"></i>Interact with actions not memorize URLs</div>
              <p>Using API helps wrangle in your API endpoints, by managing them together as a whole. Update all your endpoints from a single location. Provide developers access to your API by exporting your API endpoints for others to use.</p>
            </div>
          </div>
        </div>
      <div class="row">
          <div class="column">
            <div class="content">
              <div class="ui dividing 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. No need to manually update urls to match data, its bound automatically</p>
            </div>
          </div>
          <div class="column">
            <div class="content">
              <div class="ui dividing header"><i class="green check icon"></i>Server Traces For Humans</div>
              <p>API is built with the same trace and performance tools as other Semantic components allowing you to view english language traces of server requests letting you see where things fail.</p>
            </div>
          </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="ignored 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>

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


  </div>

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