<div class="ui header"><i class="green check icon"></i>Deal with resources not URLs</div>
<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>
<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>
</div>
</div>
@ -45,265 +44,217 @@ type : 'Draft'
<div class="column">
<div class="column">
<div class="content">
<div class="content">
<div class="ui header"><i class="green check icon"></i>Server Traces For Humans</div>
<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>
<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>
<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>
<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>
<h3 class="ui header">2. Attach an API event to an element</h3>
<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 on <code>click</code> or an input <code>oninputchange</code></p>
<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">
$('.adopt.button')
.api({
action: 'follow user'
})
;
<div class="evaluated code">
$('.follow.button')
.api({
action: 'follow user'
})
;
</div>
</div>
</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 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>
</div>
<h3 class="ui header">4. Make sure metadata is set for an element before event occurs</h3>
<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>
<div class="ui horizontal divider">Or</div>
<p>Alternatively you can modify the data before sending to server</p>
<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>
jlukic
10 years ago