api.html.eco

---
layout      : 'default'
css         : 'api'
standalone  : true

element     : 'API'
elementType : 'behavior'

title       : 'API'
description : 'API allows elements to trigger actions on a server'
type        : 'UI Behavior'
---

<script src="/javascript/library/serialize-object.js"></script>
<script src="/javascript/api.js"></script>

<%- @partial('header',  { tabs: { overview: 'Overview', usage: 'Usage',  behaviors: 'Behaviors',  settings: 'Settings' } }) %>

<div class="main ui container">
  <div class="ui active intro tab" data-tab="overview">

    <div class="test example">
      <h4 class="ui header">Integrates Seamlessly with UI</h4>
      <p>API is designed to make the process of integrating data sources to UI components seamless, <a href="#api-state-management">tying API request state</a> to UI states automatically.</p>
      <p>For example adding an API behavior to an <a href="/elements/input.html"><code>input</code></a> will occur <code>oninput</code>, while a <a href="/elements/button.html"><code>button</code></a>, will query the server <code>onclick</code>.</p>
      <div class="ui icon input">
        <i class="search icon"></i>
        <input type="text" placeholder="Type here...">
      </div>
      <div class="ui hidden divider"></div>
      <div class="ui primary button">Click Me</div>
      <div class="ui disabled button">Disabled</div>
    </div>

    <div class="no example">
      <h4 class="ui header">Preserve Templated URLs</h4>
      <p>API helps you decouple URLs from your code. Use named API actions like <code>get followers</code> instead of URLs like <code>http://foo.com/get/1.0/followers.json</code> in your code.</p>
      <div class="ignored code" data-type="javascript">
      $('.button')
        .api({
          action: 'get followers'
        })
      ;
      </div>
      <p>Centrally manage your entire API making sure you aren't caught modifying urls across your codebase. Define your endpoints using an <a href="#api-actions">intuitive templating system</a> that <a href="#passing-data">automatically passes data</a> found in your UI.</p>
      <div class="ignored code" data-type="javascript">
        $.fn.api.settings.api = {
          'get followers' : '/followers/{id}?results={count}',
          'create user'   : '/create',
          'add user'      : '/add/{id}',
          'search'        : '/query/{query}/{/sort}'
        };
      </div>
    </div>

    <div class="no example">
      <h4 class="ui header">HTTP 200 is Not Success</h4>
      <p>Parse your JSON for <code>success</code> conditions before callbacks fire, making sure server errors caught correctly, still trigger error conditions in your front end code.</p>
      <div class="ignored code">
        // Responses without this status will trigger error conditions
        $.fn.api.settings.successTest = function(response) {
          return response.status == 'OK';
        }
      </div>
    </div>

    <div class="no example">
      <h4 class="ui header">Translate APIs on the Fly</h4>
      <p>Using a third party API that uses some unruly code? Not a problem! API lets you <a href="/introduction/new.html#translates-any-api">modify an APIs raw JSON response</a> before it is consumed by your code.</p>
    </div>

    <div class="no example">
      <h4 class="ui header">Tools for Third-Party Integrations & Mocking</h4>
      <p>New powerful callbacks like <a href="#fulfilling-responses"><code>response</code></a> and <a href="#using-custom-backends"><code>responseAsync</code></a> let you asynchronously mock responses and trigger the same callbacks as your API.</p>
    </div>


  </div>

  <div class="ui intro tab" data-tab="usage">
    <div class="fixed column">
      <div class="demo content ui sticky">
        <h4 class="ui sub header">API Example</h4>
        <div class="ui fluid card">
          <div class="image">
            <img src="/images/avatar2/large/patrick.png">
          </div>
          <div class="content">
            <a class="header">Patrick Russel</a>
            <div class="description">Patrick lives in San Francisco, and studies french literature.</div>
          </div>
          <div class="ui bottom attached follow button" data-id="22">Follow</div>
        </div>
      </div>
    </div>
    <div class="examples">

      <h2 class="ui dividing header">Creating an API</h2>

      <div class="no example">
        <h4 class="ui header">API Actions</h4>
        <p><b>API</b> works by defining a set of server actions which interface elements can query. Actions are usually represented by short phrases, things like <code>save profile</code>, or <code>get followers</code> which correspond to a templated URL resource on the server.</p>
        <p>URL variables specified in actions are substituted at run-time allowing individual components to query different URLs.</p>
        <p>URLs listed in your API can include <b>required parameters</b> and <b>optional parameters</b> which may be adjusted for each call.</p>
      </div>
      <div class="no example">
        <h4 class="ui header">Required Parameters</h4>
        <div class="ui large bulleted list">
          <div class="item">Uses format <code>{variable}</code></div>
          <div class="item"><b>Will abort the request</b> if they cannot be found.</div>
        </div>
        <div class="code" data-type="javascript">
          /* Two required variables */
          $.fn.api.settings.api = {
            'get followers' : '/followers/{id}?results={count}'
          };
        </div>
      </div>
      <div class="no example">
        <h4 class="ui header">Optional Parameters</h4>
        <div class="ui large bulleted list">
          <div class="item">Uses format <code>{/variable}</code></div>
          <div class="item">Will <b>not</b> abort the request if they cannot be found.</div>
          <div class="item"><b>Will be removed</b> from the URL automatically if not available.</div>
          <div class="item">Any preceding slash before an optional parameter will be removed from the URL, allowing you to include them in resource paths.</div>
        </div>
        <div class="code" data-type="javascript">
          /* One required, one optional variable */
          $.fn.api.settings.api = {
            'get followers' : '/followers/{id}/{/sort}'
          };
        </div>
      </div>

      <div class="no example">
        <h4 class="ui header">Creating your API</h4>
        <p>You should define your endpoints <b>once in your application</b>. Usually this is done in a central configuration file included on each page.</p>
        <p>These named API endpoints are stored globally in <code>$.fn.api.settings.api</code>.</p>
        <p>Keeping your endpoints defined in one place makes sure when you update your application you will only need to update a single location with new URLs.</p>
        <div class="code" data-type="javascript">
          /* Define API endpoints once globally */
          $.fn.api.settings.api = {
            'get followers' : '/followers/{id}?results={count}',
            'create user'   : '/create',
            'add user'      : '/add/{id}',
            'follow user'   : '/follow/{id}',
            'search'        : '/search/?query={value}'
          };
        </div>
      </div>

      <div class="no example">
        <h4 class="ui header">Using URLs</h4>
        <p>Named API actions are not required to use API, you can also manually specify the URL for a request and use the same templating:</p>
        <div class="code">
        $('.search.button')
          .api({
            url: 'http://www.google.com?q={value}'
          })
        ;
        </div>
      </div>

      <h2 class="ui dividing header">Querying API Actions</h2>

      <div class="no example">
        <div class="ui info message">
          <p>The following examples work best while viewing <code>console</code> logs in your web console.</p>
        </div>
        <h4 class="ui header">Attaching API Events</h4>

        <p>API events are triggered by attaching named actions to elements on your page. These actions look up named endpoints in your API translating templated values from your element for each call.</p>

        <p>Any element can have an API action attached directly to it. By default the action will occur on the most appropriate event for the type of element. For example a button will call your server <code>onclick</code>, an input <code>oninput</code>, or a form <code>onsubmit</code>.</p>

        <p>API actions and data can be specified in Javascript on initialization:</p>
        <div class="code" data-type="html">
          <div class="ui follow button">
            Follow
          </div>
        </div>
        <div class="evaluated code">
        // translates '/follow/{id}' to 'follow/22'
        $('.follow.button')
          .api({
            action: 'follow user',
            urlData: {
              id: 22
            }
          })
        ;
        </div>
        <div class="ui horizontal divider">Or</div>

        <p>API actions and data can also be specified in metadata:</p>
        <div class="code" data-type="html">
          <div class="ui follow button" data-action="follow user" data-id="22">
            Follow
          </div>
        </div>
        <div class="code">
        // also calls '/follow/22'
        $('.follow.button')
          .api()
        ;
        </div>
      </div>

      <div class="no example">
        <h4 class="ui header">Specifying DOM Events</h4>
        <p>If you need to override what action an API event occurs on you can use the <code>on</code> parameter.</p>
        <div class="ui message">
          API requests for the following demos have been faked using API's <code>response</code> setting to avoid rate throttling from public APIs. No actual data is returned.
        </div>
        <div class="code" data-demo="true">
        $('.follow.button')
          .api({
            action: 'follow user',
            on: 'mouseenter'
          })
        ;
        </div>
      </div>

      <div class="no example">
        <h4 class="ui header">Calling Immediately</h4>
        <p>If you require API action to occur immediately use <code>on: 'now'</code>. This will still trigger the same state updates to the invoked element, but will occur immediately.</p>
        <p>
        <div class="code" data-demo="true">
        $('.follow.button')
          .api({
            action: 'follow user',
            on: 'now'
          })
        ;
        </div>
        <p>Keep in mind passing a new settings object will destroy the previous instance, and all its settings and events. If you want to preserve the previous instance, you can trigger a new request with the <code>query</code> behavior.</p>
        <div class="code" data-demo="true">
        // set-up API button with events
        $('.follow.button')
          .api({
            action: 'follow user'
          })
        ;
        // do an immediate query
        $('.follow.button')
          .api('query')
        ;
        </div>
      </div>

      <h2 class="ui dividing header">Setting-up Requests</h2>

      <div class="no example">
        <h4 class="ui header">Routing Data to URLs</h4>
        <p>If your API URLs include templated variables they will be replaced during your request by one of four possible ways, listed in of inheritance.</p>
        <p>All parameters used in a URL are encoded using <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent" target="_blank"><code>encodeURIComponent</code></a> by default, to prevent from malicious strings from affecting your query. To disable this feature you can set <a href="#settings"><code>encodeParameters: false</code></a>.
      </div>

      <div class="no routed example">
        <h4 class="ui header">1. Automatically Routed URL Variables</h4>
        <p>Some special values will be automatically replaced if specified in URL actions.</p>
        <table class="ui definition table">
          <thead>
            <tr>
              <th>Variable</th>
              <th>Description</th>
              <th>Available for</th>
            </tr>
          </thead>
          <tbody>
            <tr>
              <td>text</td>
              <td>current text value of element</td>
              <td>All elements</td>
            </tr>
            <tr>
              <td>value</td>
              <td>current input value of element</td>
              <td>Input elements</td>
            </tr>
          </tbody>
        </table>
        <div class="code" data-preview="true">
          <div class="ui search icon input">
            <i class="search icon"></i>
            <input type="text" class="search">
          </div>
        </div>
        <div class="evaluated code" data-type="javascript">
          $.fn.api.settings.api.search = '/search/?query={value}';

          $('.routed.example .search input')
            .api({
              action       : 'search',
              stateContext : '.ui.input'
            })
          ;
        </div>
      </div>

      <div class="no example">
        <h4 class="ui header">2. URL Variables Specified in Data Attributes</h4>
        <p>You can include URL values as HTML5 metadata attributes.</p>
        <p>This is often the easiest way to include unique URL data for each triggering element. For example, many follow buttons will trigger the same endpoint, but each will have its own user id.</p>
        <div class="ui ignored large warning message">
          Only variables specified in your API's URL will be searched for in metadata.
        </div>
        <div class="code" data-type="html">
          <div class="ui button" data-id="11">
            Follow Sally
          </div>
          <div class="ui button" data-id="22">
            Follow Jenny
          </div>
        </div>
        <div class="code" data-type="javascript">
          // requests different URLs for each button
          $('.follow.button')
            .api({
              action: 'follow user'
            })
          ;
        </div>
      </div>

      <div class="no example">
        <h4 class="ui header">3. Settings Specified in Javascript</h4>
        <p>URL variables and GET/POST data can be specified at run-time in the Javascript object.</p>
        <div class="code" data-type="javascript">
          $('.follow.button')
            .api({
              action : 'follow user',
              method : 'POST',
              // Substituted into URL
              urlData: {
                id: 22
              },
              // passed via POST
              data: {
                name: 'Joe Henderson'
              }
            })
          ;
        </div>
      </div>

      <div class="no example">
        <h4 class="ui header">4. Settings Returned from beforeSend</h4>
        <p>All run settings, not just URL data, can be adjusted in a special callback <code>beforeSend</code> which occurs before the API request is sent.</p>
        <div class="ui info message">
          An additional callback <code>beforeXHR</code> lets you modify the XHR object before sending. This is different than beforeSend which is used <b>to modify settings</b> before send.
        </div>
        <div class="code" data-type="javascript">
          $('.follow.button')
            .api({
              action: 'follow user',
              beforeSend: function(settings) {
                settings.urlData = {
                  id: 22
                };
                return settings;
              }
              beforeXHR: function(xhr) {
                // adjust XHR with additional headers
                xhr.setRequestHeader ('Authorization', 'Basic XXXXXX');
                return xhr;
              }
            })
          ;
        </div>
      </div>

      <h2 class="ui dividing header">Adjusting Requests</h2>

      <div class="no example">
        <h4 class="ui header">Modifying XHR</h4>
        <p>An additional callback <code>beforeXHR</code> lets you modify the XHR object before sending. This is useful for adjusting properties of the XHR request like modifying headers, before sending a request.</p>
        <div class="code" data-type="javascript">
          $('.follow.button')
            .api({
              action: 'follow user',
              beforeXHR: function(xhr) {
                // adjust XHR with additional headers
                xhr.setRequestHeader ('Authorization', 'Basic XXXXXX');
                return xhr;
              }
            })
          ;
        </div>
      </div>

      <div class="no disabled example">
        <h4 class="ui header">Disabling Requests</h4>
        <p>As a convenience, API will automatically prevent requests from occurring on elements that are currently disabled.</p>
        <div class="ui disabled button">Disabled</div>
        <div class="evaluated code">
          // this will never occur
          $('.disabled.button')
            .api({
              action: 'follow user'
            })
          ;
        </div>
      </div>

      <div class="no example">
        <h4 class="ui header">Cancelling Requests</h4>
        <p>BeforeSend can also be used to check for special conditions for a request to be made. If the <code>beforeSend</code> callback returns false, the request will be cancelled.</p>
        <div class="code" data-type="javascript" data-demo="true">
          // set somewhere in your code
          window.isLoggedIn = false;

          $('.follow.button')
            .api({
              action: 'follow user',
              beforeSend: function(settings) {
                // cancel request
                if(!isLoggedIn) {
                  $(this).state('flash text', 'Requires Login!');
                  return false;
                }
              }
            })
          ;
        </div>
      </div>

      <h2 class="ui dividing header">Passing Data</h2>

      <div class="example">
        <h4 class="ui header">1. Routed Form Data</h4>
        <p>When you use the <code>serializeForm</code> setting or attach API events on a form, API will automatically include the closest form in data sent to the server.</p>
        <p>Structured form data is beneficial over <a href="https://api.jquery.com/serialize/">jQuery's serialize</a> for several reasons:</p>
        <ul class="ui large list">
          <li><a href="https://github.com/macek/jquery-serialize-object" target="_blank">Serialize Object</a> correctly converts structured form names like <code>name="name[first]"</code> into nested object literals.</li>
          <li>Structured form data can be modified in Javascript in <code>beforeSend</code>.</li>
          <li>Form data will automatically be converted to their Javascript equivalents, for instance, checkboxes will be converted to <code>boolean</code> values.</li>
        </ul>
        <div class="ui ignored warning message">
          Structured form data requires including <a href="https://github.com/macek/jquery-serialize-object" target="_blank">macek's serialize object.</a>
        </div>
      </div>
      <div class="example">
        <h4 class="ui header">Structured Data Example</h4>
        <p>The following form shows some of the advantages of structured form data mentioned above.</p>
        <form class="ui form">
          <div class="two fields">
            <div class="field">
              <label>Name</label>
              <div class="two fields">
                <div class="field">
                  <input type="text" name="name[first]" placeholder="First Name">
                </div>
                <div class="field">
                  <input type="text" name="name[last]" placeholder="Last Name">
                </div>
              </div>
            </div>
            <div class="field">
              <label>Gender</label>
              <div class="ui selection dropdown">
                <input type="hidden" name="gender">
                <div class="default text">Gender</div>
                <i class="dropdown icon"></i>
                <div class="menu">
                  <div class="item" data-value="female">Female</div>
                  <div class="item" data-value="male">Male</div>
                  <div class="item" data-value="non-binary">Non-binary</div>
                  <div class="item" data-value="not-listed">None of the above</div>
                </div>
              </div>
            </div>
          </div>
          <div class="two fields">
            <div class="required field">
              <label>Username</label>
              <div class="ui icon input">
                <input type="text" name="username" placeholder="Username">
                <i class="user icon"></i>
              </div>
            </div>
            <div class="required field">
              <label>Password</label>
              <div class="ui icon input">
                <input type="password" name="password">
                <i class="lock icon"></i>
              </div>
            </div>
          </div>
          <div class="ui submit button">Submit</div>
        </form>
        <div class="evaluated code" data-type="javascript">
          $('form .submit.button')
            .api({
              action: 'create user',
              serializeForm: true,
              data: {
                foo: 'baz'
              },
              beforeSend: function(settings) {
                // form data is editable in before send
                if(settings.data.username == '') {
                  settings.data.username = 'New User';
                }
                // open console to inspect object
                console.log(settings.data);
                return settings;
              }
            })
          ;
        </div>
      </div>


      <div class="no example">
        <h4 class="ui header">2. Data Routed in Javascript</h4>
        <p>Server data can be specified directly when initializing an API requests.</p>
        <div class="code" data-type="javascript">
          $('.form .submit')
            .api({
              data: {
                session: 22,
                name: 'Baz'
              }
            })
          ;
        </div>
      </div>

      <div class="no example">
        <h4 class="ui header">3. Data Added in beforeSend</h4>
        <p>POST or GET data can be specified using a special callback <code>beforeSend</code>, which can be used to retrieve data before sending a request.</p>
        <div class="code" data-type="javascript">
          $('.form .submit')
            .api({
              action: 'create user',
              serializeForm: true,
              // arbitrary POST/GET same across all requests
              data: {
                session: 22
              },
              // modify data PER element in callback
              beforeSend: function(settings) {
                // cancel request if no id
                if(!$(this).data('id')) {
                  return false;
                }
                settings.data.userID = $(this).data('id');
                return settings;
              }
            })
          ;
        </div>
      </div>

      <h2 class="ui dividing header">Server Responses</h2>

      <div class="no example">
        <h4 class="ui header">Response Callbacks</h4>
        <p>Successful responses from the server will trigger <code>onSuccess</code>, invalid results <code>onFailure</code>.<p>
        <p><code>onError</code> will only trigger on <a href="https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest">XHR</a> errors, but not on invalid JSON responses.</p>
        <p>You can use the <code>onResponse</code> callback to adjust the JSON response before being parsed against a success test.
        <div class="code" data-type="javascript">
        $('.follow.button')
          .api({
            onResponse: function(response) {
              // make some adjustments to response
              return response;
            },
            successTest: function(response) {
              // test whether a JSON response is valid
              return response.success || false;
            },
            onComplete: function(response) {
              // always called after XHR complete
            },
            onSuccess: function(response) {
              // valid response and response.success = true
            },
            onFailure: function(response) {
              // request failed, or valid response but response.success = false
            },
            onError: function(errorMessage) {
              // invalid response
            },
            onAbort: function(errorMessage) {
              // navigated to a new page, CORS issue, or user canceled request
            }
          })
        ;
        </div>
      </div>

      <div class="no example">
        <h4 class="ui header">Determining JSON Success</h4>
        <p>API has special success conditions for JSON responses. Instead of providing success and failure callbacks based on the HTTP response of the request, a request is considered successful only if the server's response tells you the action was successful. The response is passed to a validation test <code>successTest</code> which can be used to check the JSON for a valid response.</p>
        <p>For example, you might expect all successful JSON responses to return a top level property signifying the success of the response:<p>
        <div class="ui ignored info message">
          You can use the <code>onResponse</code> callback to modify a server's response by returning a new translated response value before it is parsed by a success test.
        </div>
        <div class="code" data-type="json" data-title="Example Server Response">
        {
          "success": true,
          "message": "We've retrieved your data from the server"
          "data": {
            // payload here
          }
        }
        </div>
        <p>You can specify a success test to check for this <code>success</code> value. This most likely will be set globally for all API requests.</p>
        <div class="code" data-type="javascript">
        $.fn.api.settings.successTest = function(response) {
          if(response && response.success) {
            return response.success;
          }
          return false;
        };
        </div>
      </div>

      <div class="no response example">
        <h4 class="ui header">Modifying Response JSON</h4>
        <p>Since version 2.0, API includes an <code>onResponse</code> callback which lets you adjust a server's response before a response is validated, allowing you to transform your response before other callbacks fire. This is useful for situations where an API response cannot be modified, but you need the response to conform with a required JSON structure.</p>
        <div class="ui search">
          <div class="ui left icon input">
            <input class="prompt" type="text" placeholder="Search GitHub">
            <i class="github icon"></i>
          </div>
        </div>
        <div class="code" data-type="javascript">
        $('.ui.search')
          .search({
            type          : 'category',
            minCharacters : 3,
            apiSettings   : {
              url        : '//api.github.com/search/repositories?q={query}',
              onResponse : function(githubResponse) {
                var
                  response = {
                    results : {}
                  }
                ;
                if(!githubResponse || !githubResponse.items) {
                  return;
                }
                // translate GitHub API response to work with search
                $.each(githubResponse.items, function(index, item) {
                  var
                    language   = item.language || 'Unknown',
                    maxResults = 8
                  ;
                  if(index >= maxResults) {
                    return false;
                  }
                  // create new language category
                  if(response.results[language] === undefined) {
                    response.results[language] = {
                      name    : language,
                      results : []
                    };
                  }
                  // add result to category
                  response.results[language].results.push({
                    title       : item.name,
                    description : item.description,
                    url         : item.html_url
                  });
                });
                return response;
              }
            }
          })
        ;
        </div>
      </div>

      <h2 class="ui dividing header">Controlling State</h2>

      <div class="no example">
        <h4 class="ui header">UI State</h4>

        <p>API will automatically add class names for <code>loading</code> and <code>error</code>. This will let you trigger different UI states automatically as an API call progresses.</p>

        <p>If you need a different element than the triggering API element to receive state class names, you can specify a different selector using <code>settings.stateContext</code>.</p>
        <p>Using <code>stateContext</code> allows you to easily do things like trigger a loading state on a form when a submit button is pressed.</p>

        <h5 class="ui header">States Included in API Module</h5>
        <table class="ui definition celled table">
          <thead>
            <tr>
              <th>State</th>
              <th class="six wide">Description</th>
              <th>API event</th>
            </tr>
          </thead>
          <tbody>
            <tr>
              <td>loading</td>
              <td>Indicates a user needs to wait</td>
              <td>XHR has initialized</td>
            </tr>
            <tr>
              <td>error</td>
              <td>Indicates an error has occurred</td>
              <td>XHR Request returns error (does not trigger onAbort caused by page change, or if successTest fails). Stays visible for <code>settings.errorDuration</code></td>
            </tr>
            <tr>
              <td>disabled</td>
              <td>prevents API action</td>
              <td>none</td>
            </tr>
          </tbody>
        </table>
      </div>

      <div class="no example">
        <h4 class="ui header">Text State</h4>
        <p>Initializing an API action with the state module gives you more granular control over UI states, like setting an activated or de-activated state and the ability to adjust text values for each state:</p>

     <!--    <p>
          For additional examples of the possibilities available with state behaviors check the <a href="#">state module documentation</a>
        </p> -->

        <div class="code" data-demo="true">
        $('.follow.button')
          .api({
            action: 'follow user'
          })
          .state({
            onActivate: function() {
              $(this).state('flash text');
            },
            text: {
              inactive   : 'Follow',
              active     : 'Followed',
              deactivate : 'Unfollow',
              flash      : 'Added follower!'
            }
          })
        ;
        </div>
        <h5 class="ui header">States Included in State Module</h5>
        <table class="ui definition celled table">
          <thead>
            <tr>
              <th>State</th>
              <th>Description</th>
              <th>Occurs on</th>
            </tr>
          </thead>
          <tbody>
            <tr>
              <td>inactive</td>
              <td>Default state</td>
              <td></td>
            </tr>
            <tr>
              <td>active</td>
              <td>Selected state</td>
              <td>Toggled on succesful API request</td>
            </tr>
            <tr>
              <td>activate</td>
              <td>Explains activating action</td>
              <td>On hover if inactive</td>
            </tr>
            <tr>
              <td>deactivate</td>
              <td>Explains deactivating action</td>
              <td>On hover if active</td>
            </tr>
            <tr>
              <td>hover</td>
              <td>Explains interaction</td>
              <td>On hover in all states, overrides activate/deactivate</td>
            </tr>
            <tr>
              <td>disabled</td>
              <td>Indicates element cannot be interacted</td>
              <td>Triggered programatically. Blocks API requests.</td>
            </tr>
            <tr>
              <td>flash</td>
              <td>Text-only state used to display a temporary message</td>
              <td>Triggered programatically</td>
            </tr>
            <tr>
              <td>success</td>
              <td>Indicates user action was a success</td>
              <td>Triggered programatically</td>
            </tr>
            <tr>
              <td>warning</td>
              <td>Indicates there was an issue with a user action</td>
              <td>Triggered programatically</td>
            </tr>
          </tbody>
        </table>
      </div>

      <h2 class="ui dividing header">Advanced Use</h2>

        <div class="no sync mocked example">
          <h4 class="ui header">Fulfilling Responses</h4>
          <p>Since version 2.0, API includes two new parameter <code>response</code> and <code>responseAsync</code> which allows you to specify a Javascript object or a function for returning an API response. (These were previously <code>mockResponse</code> and <code>mockResponseAsync</code>.)</p>
          <div class="code" data-type="javascript" data-demo="true">
            $('.sync.mocked .button')
              .api({
                response: {
                  success: true
                }
              })
              .state({
                text: {
                  inactive   : 'Off',
                  active     : 'On'
                }
              })
            ;
          </div>
          <div class="ui toggle button">
            Off
          </div>
        </div>

        <div class="no async mocked example">
          <h4 class="ui header">Using Custom Backends</h4>
          <p>Using <code>responseAsync</code> you can specify a function which can execute your API request. This allows for you to use custom backends or wrappers outside of <code>$.ajax</code> for integrating API requests.</p>
          <div class="code" data-type="javascript" data-demo="true">
            $('.async.mocked .button')
              .api({
                responseAsync: function(settings, callback) {
                  var response = {
                    success: true
                  };
                  // do any asynchronous task here
                  setTimeout(function() {
                    callback(response);
                  }, 500);
                }
              })
              .state({
                text: {
                  inactive   : 'Off',
                  active     : 'On'
                }
              })
            ;
          </div>
          <div class="ui toggle button">
            Off
          </div>
        </div>
      </div>

  </div>

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

    <h2 class="ui dividing header">Behavior</h2>

    <p>All the following behaviors can be called using the syntax:</p>
    <div class="code">
    $('.your.element')
      .api('behavior name', argumentOne, argumentTwo)
    ;
    </div>

    <table class="ui definition celled sortable table segment">
      <thead>
        <th>Behavior</th>
        <th>Description</th>
      </thead>
      <tbody>
        <tr>
          <td>query</td>
          <td>Execute query using existing API settings</td>
        </tr>
        <tr>
          <td>add url data(url, data)</td>
          <td>Adds data to existing templated url and returns full url string</td>
        </tr>
        <tr>
          <td>get request</td>
          <td>Gets promise for current API request</td>
        </tr>
        <tr>
          <td>abort</td>
          <td>Aborts current API request</td>
        </tr>
        <tr>
          <td>reset</td>
          <td>Removes loading and error state from element</td>
        </tr>
        <tr>
          <td>was cancelled</td>
          <td>Returns whether last request was cancelled</td>
        </tr>
        <tr>
          <td>was failure</td>
          <td>Returns whether last request was failure</td>
        </tr>
        <tr>
          <td>was successful</td>
          <td>Returns whether last request was successful</td>
        </tr>
        <tr>
          <td>was complete</td>
          <td>Returns whether last request was completed</td>
        </tr>
        <tr>
          <td>is disabled</td>
          <td>Returns whether element is disabled</td>
        </tr>
        <tr>
          <td>is mocked</td>
          <td>Returns whether element response is mocked</td>
        </tr>
        <tr>
          <td>is loading</td>
          <td>Returns whether element is loading</td>
        </tr>
        <tr>
          <td>set loading</td>
          <td>Sets loading state to element</td>
        </tr>
        <tr>
          <td>set error</td>
          <td>Sets error state to element</td>
        </tr>
        <tr>
          <td>remove loading</td>
          <td>Removes loading state to element</td>
        </tr>
        <tr>
          <td>remove error</td>
          <td>Removes error state to element</td>
        </tr>
        <tr>
          <td>get event</td>
          <td>Gets event that API request will occur on</td>
        </tr>
        <tr>
          <td>get url encoded value(value)</td>
          <td>Returns <code>encodeURIComponent</code> value only if value passsed is not already encoded
        </tr>
        <tr>
          <td>read cached response(url)</td>
          <td>Reads a locally cached response for a URL</td>
        </tr>
        <tr>
          <td>write cached response(url, response)</td>
          <td>Writes a cached response for a URL</td>
        </tr>
        <tr>
          <td>create cache</td>
          <td>Creates new cache, removing all locally cached URLs</td>
        </tr>
        <tr>
          <td>destroy</td>
          <td>Removes API settings from the page and all events</td>
        </tr>
      </tbody>
    </table>


  </div>


  <div class="ui tab" data-tab="settings">
    <h2 class="ui dividing header">
      API
    </h2>

    <h4 class="ui header">
      AJAX
    </h4>
    <div class="ui info message">
      You can pass in any standard <a href="http://api.jquery.com/jquery.ajax/">jQuery AJAX setting</a> like <code>timeout</code> or <code>contentType</code> to API's settings and it will be automatically passed to the request's AJAX call.
    </div>

    <h4 class="ui header">
      API
    </h4>
    <table class="ui sortable celled definition table">
      <thead>
        <th class="three wide"></th>
        <th class="three wide">Default</th>
        <th>Description</th>
      </thead>
      <tbody>
        <tr>
          <td>on</td>
          <td>auto</td>
          <td>When API event should occur</td>
        </tr>
        <tr>
          <td>cache</td>
          <td>true</td>
          <td>Can be set to 'local' to cache <b>successful</b> returned AJAX responses when using a JSON API. This helps avoid server roundtrips when API endpoints will return the same results when accessed repeatedly. Setting to <code>false</code>, will add cache busting parameters to the URL.</td>
        </tr>
        <tr>
          <td>stateContext</td>
          <td>this</td>
          <td>UI state will be applied to this element, defaults to triggering element.</td>
        </tr>
        <tr>
          <td>encodeParameters</td>
          <td>true</td>
          <td>Whether to encode parameters with <code>encodeURIComponent</code> before adding into url string</td>
        </tr>
        <tr>
          <td>defaultData</td>
          <td>true</td>
          <td>Whether to automatically include default data like {value} and {text}</td>
        </tr>
        <tr>
          <td>serializeForm</td>
          <td>false</td>
          <td>Whether to serialize closest form and include in request</td>
        </tr>
        <tr>
          <td>throttle</td>
          <td>
            0
          </td>
          <td>How long to wait when a request is made before triggering request, useful for rate limiting <code>oninput</code></td>
        </tr>
        <tr>
          <td>throttleFirstRequest</td>
          <td>
            true
          </td>
          <td>When set to false will not delay the first request made, when no others are queued</td>
        </tr>
        <tr>
          <td>interruptRequests</td>
          <td>
            false
          </td>
          <td>Whether an API request can occur while another request is still pending</td>
        </tr>
        <tr>
          <td>loadingDuration</td>
          <td>0</td>
          <td>Minimum duration to show loading indication</td>
        </tr>
        <tr>
          <td>hideError</td>
          <td>auto</td>
          <td>The default <code>auto</code> will automatically remove error state after error duration, unless the element is a <code>form</code></td>
        </tr>
        <tr>
          <td>errorDuration</td>
          <td>2000</td>
          <td>Setting to <code>true</code>, will not remove error. Setting to a duration in milliseconds to show error state after request error.</td>
        </tr>
      </tbody>
    </table>

    <h4 class="ui header">
      Request Settings
    </h4>
    <table class="ui sortable celled definition table">
      <thead>
        <th class="three wide"></th>
        <th class="three wide">Default</th>
        <th>Description</th>
        <th>Possible Values</th>
      </thead>
      <tbody>
        <tr>
          <td>action</td>
          <td>false</td>
          <td>Named API action for query, originally specified in $.fn.settings.api</td>
          <td>String or false</td>
        </tr>
        <tr>
          <td>url</td>
          <td>false</td>
          <td>Templated URL for query, will override specified action</td>
          <td>String or false</td>
        </tr>
        <tr>
          <td>urlData</td>
          <td>false</td>
          <td>Variables to use for replacement</td>
          <td></td>
        </tr>
        <tr>
          <td>response</td>
          <td>false</td>
          <td>Can be set to a Javascript object which will be returned automatically instead of requesting JSON from server </td>
          <td>{} or false</td>
        </tr>
        <tr>
          <td>responseAsync(settings, callback)</td>
          <td>false</td>
          <td>When specified, this function can be used to retrieve content from a server and return it asynchronously <b>instead of</b> a standard AJAX call. The callback function should return the server response.</td>
          <td>function or false</td>
        </tr>
        <tr>
          <td>mockResponse</td>
          <td>false</td>
          <td>Alias of <code>response</code></td>
          <td></td>
        </tr>
        <tr>
          <td>mockResponseAsync</td>
          <td>false</td>
          <td>Alias of <code>responseAsync</code></td>
          <td></td>
        </tr>
        <tr>
          <td>method</td>
          <td>get</td>
          <td>Method for transmitting request to server</td>
          <td>Any valid http method</td>
        </tr>
        <tr>
          <td>dataType</td>
          <td>JSON</td>
          <td>Expected data type of response </td>
          <td>xml, json, jsonp, script, html, text</td>
        </tr>
        <tr>
          <td>data</td>
          <td>{}</td>
          <td>POST/GET Data to Send with Request</td>
          <td></td>
        </tr>
      </tbody>
    </table>

    <h4 class="ui header">
      Callbacks
    </h4>

    <table class="ui sortable celled definition table">
      <thead>
        <th class="three wide"></th>
        <th class="three wide">Context</th>
        <th>Description</th>
      </thead>
      <tbody>
        <tr>
          <td>beforeSend(settings)</td>
          <td>initialized element</td>
          <td>Allows modifying settings before request, or cancelling request</td>
        </tr>
        <tr>
          <td>beforeXHR(xhrObject)</td>
          <td></td>
          <td>Allows modifying XHR object for request</td>
        </tr>
        <tr>
          <td>onRequest(promise, xhr)</td>
          <td>state context</td>
          <td>Callback that occurs when request is made. Receives both the API success promise and the XHR request promise.</td>
        </tr>
        <tr>
          <td>onResponse(response)</td>
          <td>state context</td>
          <td>Allows modifying the server's response before parsed by other callbacks to determine API event success</td>
        </tr>
        <tr>
          <td>successTest(response)</td>
          <td></td>
          <td>Determines whether completed JSON response should be <a href="#determining-json-success">treated as successful</a>
          </td>
        </tr>
        <tr>
          <td>onSuccess(response, element, xhr)</td>
          <td>state context</td>
          <td>Callback after successful response, JSON response must pass <code>successTest</code></td>
        </tr>
        <tr>
          <td>onComplete(response, element, xhr)</td>
          <td>state context</td>
          <td>Callback on request complete regardless of conditions</td>
        </tr>
        <tr>
          <td>onFailure(response, element)</td>
          <td>state context</td>
          <td>Callback on failed response, or JSON response that fails <code>successTest</code></td>
        </tr>
        <tr>
          <td>onError(errorMessage, element, xhr)</td>
          <td>state context</td>
          <td>Callback on server error from returned status code, or XHR failure.</td>
        </tr>
        <tr>
          <td>onAbort(errorMessage, element, xhr)</td>
          <td>state context</td>
          <td>Callback on abort caused by user clicking a link or manually cancelling request.</td>
        </tr>
      </tbody>
    </table>

    <h2 class="ui dividing header">
      Module
    </h2>

    <p>These settings are native to all modules, and define how the component ties content to DOM attributes, and debugging settings for the module.</p>

    <table class="ui sortable celled definition table">
      <thead>
        <th></th>
        <th class="six wide">Default</th>
        <th>Description</th>
      </thead>
      <tbody>
        <tr>
          <td>name</td>
          <td>API</td>
          <td>Name used in log statements</td>
        </tr>
        <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>regExp</td>
          <td>
            <div class="code" data-type="css">
            regExp  : {
              required: /\{\$*[A-z0-9]+\}/g,
              optional: /\{\/\$*[A-z0-9]+\}/g,
            }
            </div>
          </td>
          <td>Regular expressions used for template matching</td>
        </tr>
        <tr>
          <td>selector</td>
          <td>
            <div class="code" data-type="css">
            selector: {
              disabled : '.disabled',
              form     : 'form'
            }
            </div>
          </td>
          <td>Selectors used to find parts of a module</td>
        </tr>
        <tr>
          <td>className</td>
          <td>
            <div class="code">
            className: {
              loading : 'loading',
              error   : 'error'
            }
            </div>
          </td>
          <td>Class names used to determine element state</td>
        </tr>
        <tr>
          <td>metadata</td>
          <td>
            <div class="code">
            metadata: {
              action  : 'action',
              url     : 'url'
            }
            </div>
          </td>
          <td>Metadata used to store XHR and response promise</td>
        </tr>
        <tr>
          <td>silent</td>
          <td>False</td>
          <td>Silences all console output including error messages, regardless of other debug settings.</td>
        </tr>
        <tr>
          <td>debug</td>
          <td>false</td>
          <td>Debug output to console</td>
        </tr>
        <tr>
          <td>performance</td>
          <td>true</td>
          <td>Show <code>console.table</code> output with performance metrics</td>
        </tr>
        <tr>
          <td>verbose</td>
          <td>false</td>
          <td>Debug output includes all internal behaviors</td>
        </tr>
        <tr>
          <td>errors</td>
          <td colspan="2">
            <div class="code">
            // errors
            error : {
              beforeSend        : 'The before send function has aborted the request',
              error             : 'There was an error with your request',
              exitConditions    : 'API Request Aborted. Exit conditions met',
              JSONParse         : 'JSON could not be parsed during error handling',
              legacyParameters  : 'You are using legacy API success callback names',
              missingAction     : 'API action used but no url was defined',
              missingSerialize  : 'Required dependency jquery-serialize-object missing, using basic serialize',
              missingURL        : 'No URL specified for API event',
              noReturnedValue   : 'The beforeSend callback must return a settings object, beforeSend ignored.',
              parseError        : 'There was an error parsing your request',
              requiredParameter : 'Missing a required URL parameter: ',
              statusMessage     : 'Server gave an error: ',
              timeout           : 'Your request timed out'
            }
            </div>
          </td>
        </tr>
      </tbody>
    </table>
  </div>

</div>