Attach an API event to an input, by default, it will occur oninput. Attach an API event to a button, onclick. State management is built in: rate throttling, UI state changes like active, loading, disabled, min/max request lengths and more.

Create named actions like 'follow user' and have API handle URL templating, parameters, and other annoyances for you.

Easily tie server events like AJAX loading elements using intuitive defaults based on the context inside your interface. Set maximum and minimum request times, toggle between UI states, and easily sync state between multiple elements with the same API actions.

View your API request as it occurs in your web console, get errors if required url variables are missing, and useful performance metrics.

Joined in Sep 2014

API works best by defining named API actions which can be converted to URLs for each request.

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.

URLs listed in your API can include required parameters and optional parameters which may be adjusted for each call.

Uses format {variable}

Will abort the request if they cannot be found.

Uses format {/variable}

Will abort the request if they cannot be found.

Will be removed from the url automatically if not available.

Any preceding slash before an optional parameter will be removed from the URL, allowing you to include them in resource paths.

/* Define API endpoints once globally */ $.fn.api.settings.api = { 'get followers' : '/followers/{id}?results={count}', 'follow user' : '/follow/{id}', 'search' : '/search/?query={value}' };

The following examples work best while viewing logs in your web console. This experienced is optimized for Firebug, but will also appear in webkit browsers with minor issues.

API requests for the following demos have been faked using SinonJS to avoid rate throttling from public APIs. No actual data is returned.

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 assume onclick or an input oninput, or a form onsubmit.

$('.follow.button') .api({ action: 'follow user' }) ;

If you need to override what action an API event occurs on you can use the on parameter.

$('.follow.button') .api({ action: 'follow user', on: 'mouseenter' }) ;

If you require API action to occur immediately use on: 'now'. This will still trigger the same state updates to the invoked element, but will occur immediately.

$('.follow.button') .api({ action: 'follow user', on: 'now' }) ;

Keep in mind passing a new settings object will destroy all previously attached events. If you want to preserve the events, you can trigger a new request with the the query behavior

// set-up API button with events $('.follow.button') .api({ action: 'follow user' }) ; // do an immediate query $('.follow.button') .api('query') ;

If your API urls include templated variables they will be replaced during your request by one of four possible ways (listed in order of inheritance).

Only variables specified in your URL will be searched for in metadata. Adding metadata attributes will not be automatically included in GET or POST values.

Some special values are available for routing without additional set-up

Variable	Description	Available for
text	current text value of element	All DOM elements
value	current input value of element	All input elements

$.fn.api.settings.api = { 'search' : '/search/?query={value}' }; $('.search input') .api({ action: 'search', // this setting will be explained later stateContext: '.ui.input' }) ;

You can include url values as metadata inside the DOM.

This is often easiest 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.

User 1

User 2

$('.follow.button') .api({ action: 'follow user' }) ;

URL variables can be specified at run-time in the javascript object

$('.follow.button') .api({ action: 'follow user', urlData: { id: 22 } }) ;

All run settings, not just url data, can be adjusted in a special callback beforeSend which occurs before the API request is sent.

You can also use this callback to adjust other settings before each API call

$('.follow.button') .api({ action: 'follow user', beforeSend: function(settings) { settings.urlData = { id: 22 }; return settings; } }) ;

All run settings, not just url data, can be adjusted in a special callback beforeSend which occurs before the API request is sent.

You can also use this callback to adjust other settings before each API call

$('.follow.button') .api({ action: 'follow user', beforeSend: function(settings) { settings.urlData = { id: 22 }; return settings; } }) ;

API is designed to work with APIs that return JSON objects. Instead of providiing success and failure callbacks based on the HTTP response of the request. A request is considered succesful only if the returned JSON value passes a successTest.

For example you might expect all successful JSON responses to return a top level property signifying the success of the response

{ "success": true, "message": "We've retreived your data from the server" "data": { // payload here } }

The success test function recieves the servers json response, and returns whether the result should be considered successful. Succesful results will trigger onSuccess unsuccesful results onFailure but not onError, this is reserved for responses which return XHR errors.

$('.follow.button') .api({ successTest: function(response) { return response.success || false; } onSuccess: function() { // valid response and action succeeded }, onFailure: function() { // valid response but action failed }, onError: function() { // invalid response } }) ;

Many elements like button, input, and form have loading, disabled, and active states defined.

States adjust class names on the triggering element or on the element specified by settings.stateContext.

Using stateContext allows you to easily do things like, trigger a loading state on a form when a submit button is pressed.

State	Description	API event
loading	Indicates a user needs to wait	XHR has initialized
error	Indicates an error has occurred	XHR Request returns error (does not trigger onAbort caused by page change, or if successTest fails). Stays visible for `settings.errorDuration`

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:

For additional examples of the possibilities available with state behaviors check the state module documentation

$('.follow.button') .api('setting', 'on', 'auto') .state({ text: { inactive : 'Follow', active : 'Followed', deactivate : 'Unfollow', flash : 'Added follower!' } }) .state('setting', 'onActivate', function() { $(this).state('flash text'); }) ;

State	Description	Occurs on
inactive	Default state
active	Selected state	Toggled on succesful API request
activate	Explains activating action	On hover if inactive
deactivate	Explains deactivating action	On hover if active
hover	Explains interaction	On hover in all states, overrides activate/deactivate
disabled	Indicates element cannot be interacted	Triggered programatically. Blocks API requests.
flash	Text-only state used to display a temporary message	Triggered programatically
success	Indicates user action was a success	Triggered programatically
warning	Indicates there was an issue with a user action	Triggered programatically

Needs to be written still...

	Default	Description
on	auto	When API event should occur
filter	.disabled	Selector filter for elements that should not be triggerable
stateContext	this (selector/DOM element)	UI state will be applied to this element, defaults to triggering element.
defaultData	true	Whether to include default data like {value} and {text}
serializeForm	(true, false)	Whether to serialize closest form and include in request
throttle	0	If a request is pending, additional requests will be throttled by this duration in ms. (Setting above 0 will allow multiple simultaneous requests)
regExp	regExp : { required: /\{\$[A-z0-9]+\}/g, optional: /\{\/\$[A-z0-9]+\}/g, }	Regular expressions used for finding variables in templated urls

	Default	Description	Possible Values
action		Named API action for query, originally specified in $.fn.settings.api	String or false
url	false	Templated URL for query, will override specified action	String or false
urlData	false	Variables to use for replacement
method	get	Method for transmitting request to server	post, get
dataType	JSON	Expected data type of response	xml, json, jsonp, script, html, text
data	{}	POST/GET Data to Send with Request
filter	.disabled	Selector filter for elements that should not be triggerable
stateContext	this (selector/DOM element)	UI state will be applied to this element, defaults to triggering element.

	Context	Description
onOpen	active content	Callback on element open
onClose	active content	Callback on element close
onChange	active content	Callback on element open or close

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

	Default	Description
name	Accordion	Name used in log statements
namespace	accordion	Event namespace. Makes sure module teardown does not effect other events attached to an element.
selector	selector : { accordion : '.accordion', title : '.title', content : '.content' }	Selectors used to find parts of a module
className	className : { active : 'active' }	Class names used to determine element state
debug	false	Debug output to console
performance	false	Show `console.table` output with performance metrics
verbose	false	Debug output includes all internal behaviors
errors	error : { method : 'The method you called is not defined.' }

Defining Your API

Creating Server Actions

Querying API Actions

Attaching API to UI

Specifying Events

Calling Immediately

Setting URL Variables

URL Variables

Automatically Routed Data

Data Attributes

....in Javascript

...specified in beforeSend Callback

Routing GET/POST Data

...specified in beforeSend Callback

Server Responses

Determining Success

Controlling State

API State Management

States Included in API Module

Coupling with State Module

States Included in State Module

API

Behavior

Request Settings

Callbacks

Module