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)
.fromdate("1/1/1970") // <-- any parsable date value
.todate(Date.parse("1/1/2040")) // <-- or a date (or number)
.sort("votes")
.min(0)
.max(10)
.order("desc")
.page(2)
.pagesize(100);
ID Handling:
For queries that require a 'vectorized id', you may specify a single number or string, an array of numbers or strings or simply provide a semi-colon delimited list as described on the help pages.
site.Questions().ById(1).invoke();
site.Questions().ById("1").invoke();
site.Questions().ById([1, 2]).invoke();
site.Questions().ById("1;2").invoke();
The same principal applies to any API parameter that calls for a list of string.
site.Questions().tagged(["app", "library"]).invoke();
site.Questions().tagged(["app;library"]).invoke();
Content Parameters
The boolean content flags are prefixed with 'with' to avoid collisions
site
.Questions()
.withAnswers(true)
.withBody(true)
.withComments(true)
.invoke();
Date Handling:
All dates in Soapi, in and out, are in JavaScript date format and are in Local time. If the UTC value is needed, simply use the methods on the Date object.
Any parameter that requires or will accept a Date (unix timestamp on the API side) values will accept any parsable representation of a date.
site
.Questions()
.fromdate("1/1/1980")
.todate(Date.parse("1/1/2020"))
.invoke();
Min/Max
Min/Max, the types and values, are contextually bound to the sort that is applied to the query.
When Date values are indicated by the selected sort, the same date parsing features described above apply.
For more information about min/max see: How to use min/max with sort
Paging:
In addition to the .page() and .pagesize() parameters, which behave as documented on the API help pages, Soapi.JS2 supports fetching of multiple pages using the .pagecount() parameter.
site.Questions()
.tagged("c#").pagecount(3)
.invoke(function(data) {
// three pages worth of items
});
To retrieve all available pages, specify .pagecount(0).
Soapi.JS2 ALPHA does not yet provide a mechanism for cancellation of a paging operation, so you will want to be aware of the potential size of the dataset you are asking for before sending an 'all pages' requests, which makes the .total() method even more useful....
All queries expose an async .total() method that will return the total count of records that match the query as parameterized.
site.Questions().tagged("c#").total(function(total) {
alert("there are " + total + " c# questions");
});
NEXT: Stubs (partially populated objects)
