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.

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.

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.

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

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.

Adopt

API 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.

To do this you must include a list of named endpoints before calling $.api on any page. The easiest way to do this is to have it available in a stand-alone configuration file.

For the sake of this example we will use Github's public API as an example

/* "Config.js" - Define API endpoints once globally */ $.fn.api.settings.api = { 'follow user' : '/api/follow/{$id}', 'user info' : '/api/user/{$id}' };

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 click or an input oninputchange

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

API couples well with ui state, a component used for managing text state and class names of elements.

State will automatically apply the class active 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.

$('.adopt.button') .state({ text: { inactive : 'Adopt', active : 'Adopted', deactivate : 'Undo', flash : 'Success' } }) ;

When an API action occurs, templated url data is replaced with data you specify to be sent to the server.

Or

Alternatively you can modify the data before sending to server

$('.adopt.button') .api('setting', 'beforeSend', function(settings) { settings.urlData.id = 5209; return settings; }) ;

Demo

1. Define Your API

2. Attach an API event to an element

2. Specify state changes to text or appearance (optional)

4. Make sure metadata is set for an element before event occurs