If the above REST API does not cover your needs, you can design your own REST API.
We now explain how to do a simple API for just retrieve a company with its ticker.
The first thing you need to know is that, whenever you write a public query, its results becomes available through a REST call.
http://project-name.xbrl.io/my-query.jq
For example, you can call the query returning all entities with the following URI:
http://project-name.xbrl.io/companies/all.jq
For more elaborate queries though, the following endpoint is better suited:
http://project-name.xbrl.io/v1/_queries/public/companies/all.jq
However, it is more strict, meaning that it will complain if the query has side effects and if the method is GET -- you have to use POST for side-effecting queries.
Finally, this more elaborate endpoint is stricter about types, meaning, you need to use a function to declare the type of what the query returns.
For the sake of simplicity, we use the simpler endpoint in ths rest of this chapter.
You will need to read parameters from the query string. There is a function named parameter-values, which lives in the http://www.28msec.com/modules/http-request namespace. It takes a parameter name, and returns the sequence of all its values (it may have several if it appears several times in the request URL).
Example - Read a parameter's value(s) from the query string
import module namespace companies =
"http://xbrl.io/modules/bizql/profiles/sec/companies";
import module namespace request =
"http://www.28msec.com/modules/http/request";
let $tickers := request:parameter-values("t")
return companies:companies-for-tickers($tickers)
Here is a possible way to invoke this query via the REST API:
GET http://project-name.xbrl.io/rest-api/query-string-parameter.jq?t=wmt&t=GOOG
There are a few more useful functions. For example, request:method-get() , method-post() , etc, return a boolean and allow you to know which method the consumer used.
Until now, we used the request module. Likewise, there is a response module http://www.28msec.com/modules/http-response , with which you can tune the output (HTTP code, MIME type, etc).
Example - Read a parameter's value(s) from the query string
import module namespace companies =
"http://xbrl.io/modules/bizql/profiles/sec/companies";
import module namespace request =
"http://www.28msec.com/modules/http-request";
import module namespace response =
"http://www.28msec.com/modules/http-response";
let $tickers := request:param-values("t")
return switch(true)
case request:method-get() and exists($tickers)
return {
response:content-type("application/json");
companies:companies-for-tickers($tickers)
}
case request:method-get() and empty($tickers)
return {
response:status-code(404);
()
}
default return {
response:content-type("text/plain");
"Method not supported."
}
The above query reacts on the method and on whether companies are found to demonstrate a few of the available features: