You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
262 lines
10 KiB
262 lines
10 KiB
---
|
|
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>Create named actions like <code>'follow user'</code> and have API handle URL templating, parameters, and other annoyances for you.</p>
|
|
</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 in your web console, get errors if required url variables are missing, and useful performance metrics.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="ui intro tab" data-tab="usage">
|
|
<div class="fixed column">
|
|
<div class="demo content ui sticky">
|
|
<div class="ui fluid card">
|
|
<div class="image">
|
|
<img src="/images/avatar/large/stevie.jpg">
|
|
</div>
|
|
<div class="content">
|
|
<a class="header">Stevie Feliciano</a>
|
|
<div class="meta">
|
|
<span class="date">Joined in Sep 2014</span>
|
|
</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">Define Your API</h4>
|
|
<p><b>API</b> works best by defining named API actions which can be converted to URLs for each request/</p>
|
|
<p>To do this you must define your endpoints once in your application before making requests. Usually this is done in a central configuration file included on each page.</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>
|
|
<p><b>Required Parameters</b> will abort the request if they cannot be replaced when triggered.</p>
|
|
<p><b>Optional Parameters</b> will be removed from the url if are not included when triggered. In addition, any trailing slashes before an optional parameter will also be removed from the URL, allowing you to include them in resource paths.</p>
|
|
<div class="code">
|
|
$.fn.api.settings.api = {
|
|
'endpoint': 'api/{required}/{/optional}/{/optional2}'
|
|
};
|
|
</div>
|
|
|
|
<div class="code" data-type="javascript">
|
|
/* Define API endpoints once globally */
|
|
$.fn.api.settings.api = {
|
|
'get user' : '/user/{id}',
|
|
'get followers' : '/followers/{id}?results={count}',
|
|
'follow user' : '/follow/{id}',
|
|
'add user' : '/add/{id}',
|
|
};
|
|
</div>
|
|
</div>
|
|
|
|
<h2 class="ui dividing header">Calling API Actions</h2>
|
|
|
|
<div class="no example">
|
|
<h4 class="ui header">Automatic Events</h4>
|
|
|
|
<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 <code>onclick</code> or an input <code>oninput</code>.</p>
|
|
|
|
<div class="ui info message">
|
|
AJAX requests for the following demos have been faked using <a href="http://sinonjs.org/">SinonJS</a> to avoid rate throttling from public APIs.
|
|
</div>
|
|
|
|
<div class="evaluated code">
|
|
$('.follow.button')
|
|
.api({
|
|
action: 'follow user'
|
|
})
|
|
;
|
|
</div>
|
|
</div>
|
|
|
|
<div class="no example">
|
|
<h4 class="ui header">Manual Events</h4>
|
|
<p>If you need to manually override what action an API event occurs on you can use the <code>on</code> parameter. In addition, using the special parameter <code>on: 'now'</code> will trigger the api event immediately.</p>
|
|
<div class="code" data-demo="true">
|
|
$('.follow.button')
|
|
.api({
|
|
action: 'get user',
|
|
on: 'hover'
|
|
})
|
|
;
|
|
</div>
|
|
</div>
|
|
|
|
<div class="no example">
|
|
<h4 class="ui header">Calling Immediately</h4>
|
|
<p>If you need to manually override what action an API event occurs on you can use the <code>on</code> parameter. In addition, using the special parameter <code>on: 'now'</code> will trigger the api event immediately.</p>
|
|
<div class="code" data-demo="true">
|
|
$('.follow.button')
|
|
.api({
|
|
action: 'follow user',
|
|
on: 'now'
|
|
})
|
|
;
|
|
</div>
|
|
</div>
|
|
|
|
<h2 class="ui dividing header">Setting Conditions</h2>
|
|
|
|
<div class="no example">
|
|
<h4 class="ui header">URL Variables For API Request</h4>
|
|
<p>Templated variables set in your API are replaced during your request in three different ways.</p>
|
|
|
|
<h5 class="ui header">...by Data Attributes</h5>
|
|
<p>If many elements trigger a similar function, it is often easiest to include data attribute for each instance with the specific url variables</p>
|
|
<div class="code" data-type="html">
|
|
<div class="ui follow button" data-id="11">Follow User1</div>
|
|
<div class="ui follow button" data-id="22">Follow User2</div>
|
|
</div>
|
|
<h5 class="ui header">....in Javascript</h5>
|
|
<p>URL variables can be specified at run-time in the javascript object</p>
|
|
<div class="code" data-type="javascript">
|
|
$('.follow.button')
|
|
.api({
|
|
action: 'follow user',
|
|
urlData: {
|
|
id: 22
|
|
}
|
|
})
|
|
;
|
|
</div>
|
|
<h5 class="ui header">...returned values from beforeSend Callback</h5>
|
|
<p>In addition all parameters can be adjusted in a special callback <code>beforeSend</code> which occurs, quite intuitively, before the API request is sent.</p>
|
|
<p>You can also use this callback to adjust other settings before each API call</p>
|
|
<div class="code" data-type="javascript">
|
|
$('.follow.button')
|
|
.api({
|
|
action: 'follow user',
|
|
beforeSend: function(settings) {
|
|
settings.urlData = {
|
|
id: 22
|
|
};
|
|
return settings;
|
|
}
|
|
})
|
|
;
|
|
</div>
|
|
</div>
|
|
|
|
<div class="no example">
|
|
<h4 class="ui header">3. Defining UI State</h4>
|
|
|
|
<p>Many elements like <a href="/elements/button.html">button</a>, <a href="/elements/input.html">input</a>, and <a href="/collections/form.html">form</a> have loading, disabled, and active states defined.</p>
|
|
|
|
<div class="ui disabled button">Learn more about states</div>
|
|
|
|
<p>API will automatically attach a <b>Loading</b> state when an API request is triggered, additional states can be attached using state behaviors, an optional component that couples well with API behaviors.</p>
|
|
|
|
<p>If state is initialized, it will automatically apply the class <code>active</code> on API success, and update any text nodes with new values specified.</p>
|
|
|
|
<p>State also includes other states:</p>
|
|
<ul class="ui list">
|
|
<li><b>Inactive</b> - Default state</li>
|
|
<li><b>Active</b> - API request is completed succesfully</li>
|
|
<li><b>Enable</b> - Text on hover if currently in inactive state</li>
|
|
<li><b>Deactivate</b> - Text on hover if currently in active state</li>
|
|
<li><b>Hover</b> - Text appears on hover regardless of state</li>
|
|
<li><b>Flash</b> - Text appears on element for time duration set by <code>flashDuration</code>
|
|
</ul>
|
|
|
|
<div class="code" data-demo="true">
|
|
$('.follow.button')
|
|
.state({
|
|
text: {
|
|
inactive : 'Adopt',
|
|
active : 'Adopted',
|
|
deactivate : 'Undo',
|
|
flash : 'Success'
|
|
}
|
|
})
|
|
;
|
|
</div>
|
|
</div>
|
|
|
|
<div class="no example">
|
|
<h4 class="ui header">4. Make sure metadata is set for an element before event occurs</h4>
|
|
|
|
<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>
|
|
|
|
<div class="ui tab" data-tab="examples">
|
|
<!-- Search Example !-->
|
|
|
|
|
|
<!-- Tab Manual Example !-->
|
|
|
|
|
|
<!-- Tab Auto Example !-->
|
|
|
|
|
|
</div>
|
|
|
|
<div class="ui tab" data-tab="settings">
|
|
|
|
</div>
|
|
|
|
</div>
|
|
</body>
|
|
</html>
|