Return to Revisions

Soapi.Route Usage

soapi.generated.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, may be re-used as often as desired.

Route exposes a single function, getResponse(success,error,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"}
• timeout (optional) - number - The default timeout value is 30,000, or 30 seconds. If this is not acceptable, simply provide a timeout value in ms.

example:

var route = factory.Users();

route.getResponse(
    function success(data) {
        var usernames = [];
        alert("response contained " + data.users.length + " users");
    },
    function error(err) {
        alert("Error: " + err.code + " " + err.message);
    },
    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);

resulting in a url resembling the following (url-encoded, of course):

http://api.xxx.com/0.8/users/1;2;3;14&key=myApiKey

The other parameters of the route may be explicitly set on the Route object itself or appied via the Route.applyParameters function with an object literal.

With the exception of any parameter that is described in the API help-pages as 'semicolon-delimited' or 'unix timestamp' as defined as described in the help pages.

'semicolon-delimited' parameters, which can be set in the factory method call, are defined as Array 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 applyParameters in the form of a QUnit test:

asyncTest("AnswersByIdSanityCheck", function() {
    expect(1);
    var factory = new Soapi.RouteFactory('api.stackoverflow.com', apiKey);
    var route = factory.AnswersById(2917525, 2701766);
    
    route.applyParameters({
        //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.answers.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 = new 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.answers.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