Return to Revisions

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 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 appied 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 http://soapi.info/images/soapi.JS.intellisense1.png

Next: Complete Route Listing - suprisingly simple mastery of the API via Soapi.js lies here