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.
153 lines
6.1 KiB
153 lines
6.1 KiB
---
|
|
layout : 'default'
|
|
css : 'api'
|
|
|
|
title : 'API'
|
|
description : 'API allows UI elements to send events to the server'
|
|
type : 'Draft'
|
|
|
|
themes : ['Default']
|
|
---
|
|
|
|
<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>
|