**Routes: what are they and how to use them**
Soapi.js defines `Route` 'classes' for each and every route, or URL, in the Stack Overflow 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 defined parameter objects or JSON literals will be covered later in this post.
A `Route`, once constructed via the factory methods on `RouteFactory`, may be re-used as often as desired.
`Route` exposes two functions
- `getResponse(success, error, timeout)`.
- `getPagedResponse(success, error, pageCallback, timeout)`.
**`Route.getResponse`** parameters:
- `success` (required) - `function(data)` - `data` will be a JavaScript object (jsob) built from the response JSON as defined on the route's help-page.
- `error` (optional) - `function(err)` - `err` will be a jsob shaped like this: `{ code: number , message: "String", URL: "String"}`
- `timeout` (optional) - `number` - The default timeout value is 10,000, or 10 seconds. If this is not acceptable, simply provide a timeout value in ms.
example:
var route = factory.Users();
route.getResponse(
function success(data) {
alert("response contained " + data.items.length + " users");
},
function error(err) {
alert("Error: " + err.code + " " + err.message);
},
2000);
**`Route.getPagedResponse`** parameters:
- `success` (required) - `function(data)` - `data` will be a JavaScript object (jsob) built from the response JSON as defined on the route's help-page.
- `error` (optional) - `function(err)` - `err` will be a jsob shaped like this: `{ code: number , message: "String", URL: "String"}`
- `pageCallback` (optional) - `function(data)` - `data` will be a JavaScript object (jsob) built from the response JSON as defined on the route's help-page. You may examine this object to determine if you would like to terminate the paged request. Simply return `true` if you wish to terminate and receive the current aggregated results in your `success` function.
- `timeout` (optional) - `number` - The default timeout value is 10,000, or 10 seconds. If this is not acceptable, simply provide a timeout value in ms.
example:
var route = factory.Users();
route.page = 1;
route.pagesize = 100;
route.getResponse(
function success(data) {
alert("response contained " + data.items.length + " users");
// should be 500, as we fetched 5 pages of 100
},
function error(err) {
alert("Error: " + err.code + " " + err.message);
},
function pageCallback(data) {
return data.page == 5;
},
2000);
**RouteFactory Method Parameters**
Routes that require an `id`, typically a semi-colon delimited list of identifiers, the factory method will accept id values as a param array, e.g. `(id1,id2,id3,...)` and construct the 'vectorized, semi-colon delimited' string for you.
example:
var route = factory.UsersById(1,2,3,14, { pagesize: 5});
resulting in a URL resembling the following (URL-encoded, of course):
http://api.xxx.com/0.8/users/1;2;3;14&pagesize=5&key=myApiKey
The other parameters of the route may be supplied as an object literal in the factory method, as shown, explicitly set on the `Route` object itself or applied via the `Route.applyParameters` function with an object literal.
'semicolon-delimited' parameters, which can be set in the factory method call, can be set as a string, `('1;2;3')`, a param array, `(1,2,3)` or an array, ([1,2,3]), and are properly encoded by `getResponse`.
'unix timestamp..' parameters are set as JavaScript `Date` and are properly converted and encoded by `getResponse`.
Setting parameters directly on the `Route` object will, I think, be of more interest to Visual Studio users who may take advantage of the intellisense and code completion provided by `soapi.generated-vsdoc.js`. This topic will be covered in detail in the **Intellisense Support** post.
**example in the form of a QUnit test:**
asyncTest("AnswersByIdSanityCheck", function() {
expect(1);
var factory = Soapi.RouteFactory('api.stackoverflow.com', apiKey);
var route = factory.AnswersById(2917525, 2701766, {
//id is set in factory method call
// these are default values that do not result in a
// parameter being added to the URL
body: false,
comments: false,
sort: "",
order: "",
min: 0,
max: 0,
fromdate: 0,
todate: 0,
page: 0,
pagesize: 0
});
route.getResponse(
function (data) {
ok(data.items.length==2, 'async call succeeded, count inaccurate');
start();
},
function(err) {
ok(err.message);
start();
}, 5000);
**example direct member set (with code completion and inline documentation) in the form of a QUnit test:**
asyncTest("AnswersByIdSanityCheck3", function() {
expect(1);
var factory = Soapi.RouteFactory('api.stackoverflow.com', apiKey);
var route = factory.AnswersById(2917525, 2701766);
route.body = false;
route.comments = false;
route.sort = "";
route.order = "";
route.min = 0;
route.max = 0;
route.fromdate = 0;
route.todate = 0;
route.page = 0;
route.pa
route.getResponse(
function(data) {
ok(data.items.length == 2, 'async call succeeded, question count inaccurate');
start();
},
function(err) {
ok(err.message);
start();
}, 5000);
});
![alt text][1]
**Next**: [Complete Route Listing][2] - surprisingly simple mastery of the API via Soapi.js lies here
[1]: https://i.sstatic.net/AnRU4.png
[2]: https://stackapps.com/questions/494/soapi-js/955#955