Tag Info

Usage Example: Stack Exchange Site Monitor
JavaScript Site Monitor in 20 lines of code or less....
Demonstrates the use of Soapi.js to query stackauth.com to get an up-to-date list of Stack Exchange sites and then polling /stats for each one on a revolving timer.
$(document).ready(function siteMonitor() {
var apiKey = '';
new ...

StackCenter gives me my overall rep, as well as rep and comments per site. But it doesn't give me a dashboard of all my recent question votes, answer votes, and comments.
I'd like to see my "recent" view more or less with the existing layout -- because it works well, and the "summary" and other detail tabs are useful -- but one view that contains all the ...

Querying Stack Exchange Users
You may leverage the Filtering and Sorting capabilities of the Ajax grid to shape results based upon the entire Stack Exchange user base.
You may export the contents of the current grid page to CSV.

IIS ASP.net, by default, prohibits service of many file extensions, .cs is one.
So the request is being killed by IIS ASP.net before it hits the REST handlers.
This can be fixed fairly easily by striking the following entry, if so desired...
%SYSTEM%\Microsoft.NET\Framework\v2.0.50727\CONFIG\Web.Config
....
<httpHandlers>
<add path="*.cs" ...

soapi.js vs soapi-vsdoc.js
While the -vsdoc.js is quite large, it is never served. It is, if you are using Visual Studio, used to provide intellisense services, otherwise you may either delete it or keep it around as reference.
The file that actually defines the domain types at runtime, soapi.js, is quite small, 9.5k packed, in that it only contains meta ...

Visual Studio JavaScript Intellisense and Code Completion Support
Overview
Included in the .zip is soapi-vsdoc.js. This file contains JavaScript code documented following the Visual Studio JavaScript Intellisense Documentation format.
This file, while of special interest to users of Visual Studio, contains complete documentation of the API, including all ...

Paging Operations
The majority of operation against the API involve paging operations.
Most of the work and complexity of dealing with paged results have been encapsulated by the Route.GetPagedResponse() method.
Soapi.RouteFactory("api.stackoverflow.com", apiKey)
.Tags({ pagesize: 1 }) // contrived page size
.getPagedResponse(function ...

Throttled Request Queue
To provide transparent compliance with the throttle limite, Soapi.js includes an integrated throttled request queue.
The queue is integrated into the library and is transparent, requiring no additional coding or consideration.
The current default queue interval is 170ms.
This means that, with the request queue and request cache, ...

Request Caching
In the interest of application performance and to prevent inadvertent api 'abuse', Soapi.js includes an integrated request cache that stores the results of each unique request url for a default (and minimum) period of 60 seconds.
The caching duration may be increased for individual routes as per your application's needs.
e.g. perhaps your ...

Relational Queries
When JSON results are received from the API, they are used to build domain objects from the Soapi.Domain namespace.
Upon these objects are strategically placed queries, the same queries you will find rooted on the Site object, that are pre-keyed to return data for that object.
NOTE:
Query methods are upper-cased to make it clear that ...

Api Coverage
Every path in the API has a reciprocal query rooted on the Soapi.Domain.Site object.
The query syntax has been constructed to be as intuitive as possible.
A complete map of Soapi.JS2 query path to API rest path follows.
Api Routes
/answers/{id}
site.Answers().ById(704).invoke(/*handlers here*/);
...

Find Stack Exchange Users By UserName OR Email
You may find any user in the Stackiverse by the email address they supply when registering on any Stack Exchange site or by full or partial user name (display_name).
JSON API
{
"email_address": "foo@bar.com", // yes - this is a real account
"items": [{
"site_url": ...

Under the hood
The code required to produce the pretty output, for what it does, is fairly brief but it does distract from the core functions that do all the heavy lifting.
Stack Users Lite is built upon 3 API calls
/sites (Route.ApiSites)
/users (Route.Users)
/users/{id}/associated (Route.UsersByIdAssociated)
Route.ApiSites
Route.ApiSites is a ...

ApiContext
Query based Soapi.JS2 usage is rooted on the ApiContext object. This object maintains the list of Site that are available for query and provides central services.
You gotta have one and it must be initialized.
var context = new Soapi.ApiContext(apiKey);
context.initialize(function onSuccess(){
// proceed
}, function onFailed(error){
...

JSON API
Note:
I am just one developer and I do not have the time/money/resources to maintain an industrial grade public data source. If it is determined for any reason that you are not using the API in the capacity and terms indicated, your IP will be banned with a quickness.
I will shortly implement a private key system. Those interested in using the ...

Sample Code: SiteMonitor
SiteMonitor is an example of using Soapi.JS2 to retrieve and display status and statistics for all of the sites in the Stack Exchange network.
SiteMonitor.htm can be found in the Soapi.JS2 source download.
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" ...

Throttling and Caching
In order to provide maximum data throughput and at the same time protect your application from, and obviate coding for, server errors due to throttle rate violations and/or polling abuse, Soapi.JS2 implements a caching throttle implementation, Soapi.Net.ThrottleCache, that throttles on a sliding window with a governor supplemented by ...

Parameterization And Paging
Overview:
Soapi.JS2 facilitates query parameterization using 'fluent' or 'chained' setter methods and maintains full parity with the documention found on the API help pages.
For example: the route /answers/{id} is serviced by Soapi.JS2 as follows:
site.Answers()
.ById(200)
.withBody(true)
.withComments(true)
...

Complete Route Listing
The RouteFactory's factory methods are consistently and intuitively named by convention to make banging out code without intellisense code completion as painless as possible.
Here is a complete list of the RouteFactory methods and the API equivalent. Starting to see a pattern? ;-)
Api Routes
AnswersById = /answers/{id}
...

Basic Usage Example 01
var ctx = new Soapi.ApiContext(apiKey);
ctx.initialize(function() { // ctx.initialize loads sites from stackauth
var site = ctx.find("api.stackapps.com"); // site is Soapi.Domain.Site
// if you are using Visual Studio, you can use the constructor of any domain '
// object as a Cast operation to enable intellisense...
...

VectorizedIdList
Many routes accept a 'vectorized list of identifiers'. This allows you to retrieve data for multiple items and helps maximize efficiency and performance.
The problem is that the 'vectorized list' is part of the url path, which much remain below a certain length (around 240) to avoid 400 (Bad Request) errors.
the VectorizedIdList allows ...

Packaging Soapi.js
The process of packaging Soapi.js for distribution may be of interest to users of Soapi.js as well as others interested in using Visual Studio to automate the build and packaging of JavaScript resources, including documentation.
Requirements:
Visual Studio 2008
Ajax Minifier 1.1
Java runtime (TODO: see if ikvm can run jsdoc. I doubt ...

Date Handling
As of RC2, Soapi.js is Dates in, Dates out. No more dealing with unix timestamps.
This includes input parameters, todate, fromdate, min and max (when applicable) and all response object date properties e.g. creation_date is converted to a JavaScript date object before it is passed to your success function.
todate, fromdate may also be ...

Enumerated Constants, or enums, in Soapi.js
The advantages of using enums include the elimination of magic strings scattered about your codebase and the ability to update all references to an enum value in one location.
Typically, in a statically typed language, enums are readonly or immutable values. While this concept is alien to the dynamically typed ...

Routes: what are they and how to use them
Soapi.js defines Route 'classes' for each and every route, or url, in the StackOverflow API.
A Route is primarily a 'class' off of which to hang the url path and define the parameters for the url. Specifying required 'id' parameters in the factory method call and the application of parameters via explicitly ...