The Jorum API

Jorum provides access to various data via RESTful API endpoints, implemented as described below.

The core API outputs data in JSON format.

The reporting API endpoints support three different output formats: JSON, XML and CSV. Output format may be specified through a process of content-negotiation with the server, or by using a file extension in the request. For example, a request for "downloads.csv" will always produce a CSV file, whereas "downloads" may produce a JSON, XML or CSV depending on the client's HTTP-Accept headers. The server will default to JSON format where there is any uncertainty.

/api

GET

description

This documentation page, giving a brief overview of the Jorum API.

arguments

There are no arguments for this method

example

GET

http://beta.jorum.ac.uk/api

Returns this page

/api/query

GET

POST

description

A direct route to the Jorum backend, with full ElasticSearch query parameters, returning a JSON result object.

It is equivalent to the /indexname/indextype/_search route in ElasticSearch.

arguments

See the ElasticSearch Search API documentation for a full list of parameters.

example

GET

http://beta.jorum.ac.uk/api/query?q=*:*

Returns the first page of all OERs in the index in JSON format

GET

http://beta.jorum.ac.uk/api/query?q=id:1920

Returns the OER document with the ID=1920 in JSON format

GET

http://beta.jorum.ac.uk/api/query?q=title:fish&size=18

Returns the first 18 OER documents with 'fish' in the title, in JSON format

POST

http://beta.jorum.ac.uk/api/query


{ "query": { "match_all": {} }, "facets": { "facets": { "date_histogram": { "interval": "month", "field": "statistics.time" }, "facet_filter": { "term": { "statistics.event_type": "view" } }, "nested": "statistics" } }, "size": 0 }

Returns a histogram of views (grouped by month) in JSON format

/find/report/query.json

GET

POST

description

An alias for /api/query

It is equivalent to the /indexname/indextype/_search route in ElasticSearch.

arguments

See the ElasticSearch Search API documentation for a full list of parameters.

example

GET

http://beta.jorum.ac.uk/find/report/query.json?q=*:*

Returns the first page of all OERs in the index in JSON format

GET

http://beta.jorum.ac.uk/find/report/query.json?q=id:1920

Returns the OER document with the ID=1920 in JSON format

GET

http://beta.jorum.ac.uk/find/report/query.json?q=title:fish&size=18

Returns the first 18 OER documents with 'fish' in the title, in JSON format

POST

http://beta.jorum.ac.uk/find/report/query.json


{ "query": { "match_all": {} }, "facets": { "facet": { "date_histogram": { "interval": "month", "field": "statistics.time" }, "facet_filter": { "term": { "statistics.event_type": "view" } }, "nested": "statistics" } }, "size": 0 }

Returns a histogram of views (grouped by month) in JSON format

/find/report/query.xml

GET

POST

description

An alias for /api/query

Results are automatically transformed from JSON to XML.

It is equivalent to the /indexname/indextype/_search route in ElasticSearch.

arguments

See the ElasticSearch Search API documentation for a full list of parameters.

example

GET

http://beta.jorum.ac.uk/find/report/query.xml?q=*:*

Returns the first page of all OERs in the index in XML format

GET

http://beta.jorum.ac.uk/find/report/query.xml?q=id:1920

Returns the OER document with the ID=1920 in XML format

GET

http://beta.jorum.ac.uk/find/report/query.xml?q=title:fish&size=18

Returns the first 18 OER documents with 'fish' in the title, in XML format

POST

http://beta.jorum.ac.uk/find/report/query.xml


{ "query": { "match_all": {} }, "facets": { "facet": { "date_histogram": { "interval": "month", "field": "statistics.time" }, "facet_filter": { "term": { "statistics.event_type": "view" } }, "nested": "statistics" } }, "size": 0 }

Returns a histogram of views (grouped by month) in XML format

/find/report/query.csv

GET

POST

description

This method performs the same queries as /find/report/query.json above, and then transforms either the {facets.facet.entries} array or the {hits.hits} array (in that order of preference) into CSV format. This limitation is because of the 'flat' nature of CSV.

Note that because EITHER the {facets.facet.entries} array OR the {hits.hits} array are transformed into CSV (but not both), the results will be incomplete. JSON or XML should be used to obtain the full result set.

It is equivalent to the /indexname/indextype/_search route in ElasticSearch.

arguments

See the ElasticSearch Search API documentation for a full list of parameters.

example

GET

http://beta.jorum.ac.uk/find/report/query.csv?q=*:*&size=100

Returns the first 100 of all OERs in the index in CSV format

GET

http://beta.jorum.ac.uk/find/report/query.csv?q=id:1920

Returns the OER document with the ID=1920 in CSV format

GET

http://beta.jorum.ac.uk/find/report/query.csv?q=title:fish&size=18

Returns the first 18 OER documents with 'fish' in the title, in CSV format

POST

http://beta.jorum.ac.uk/find/report/query.csv


{ "query": { "match_all": {} }, "size": 100 }

Returns the first 100 OERs in CSV format

/find/report/views.json

/find/report/downloads.json

/find/report/uploads.json

GET

POST

description

Utility reports for returning histograms of the numbers of views, downloads and uploads, in JSON format.

The reports are equivalent to a date-histogram facet in ElasticSearch.

arguments

interval

The aggregation level to use when calculating the histogram. Valid values are: year, quarter, month, week, day, hour, minute.

If not specified, this will default to 'month'. See also the interval field in the Date Histogram Facet documentation for ElasticSearch.

from

The date, in ISO 8601 format (YYYY-MM-DD), from which to limit the events to.

If not specified, this will default to '1970-01-01T00:00:00.000Z'.

to

The date, in ISO 8601 format (YYYY-MM-DD), to which to limit the events to.

If not specified, this will default to '3000-01-01T00:00:00.000Z'.

resourceid

The resourceid with which to limit the events to.

If not specified, this constraint will be ignored.

example

GET

http://beta.jorum.ac.uk/find/report/views.json?resourceid=1920

Returns the histogram of views for resourceid=1920 in JSON format

GET

http://beta.jorum.ac.uk/find/report/downloads.json?interval=week&from=2012-09-01&to=2012-09-30

Returns the histogram of downloads for all OERs in the system for September 2012, aggregated by week, in JSON format

GET

http://beta.jorum.ac.uk/find/report/uploads.json

Returns the histogram of uploads for all OERs in the system in JSON format, using default argument values

/find/report/views.xml

/find/report/downloads.xml

/find/report/uploads.xml

GET

POST

description

Utility reports for returning histograms of the numbers of views, downloads and uploads, in XML format.

The reports are equivalent to a date-histogram facet in ElasticSearch.

arguments

interval

The aggregation level to use when calculating the histogram. Valid values are: year, quarter, month, week, day, hour, minute.

If not specified, this will default to 'month'. See also the interval field in the Date Histogram Facet documentation for ElasticSearch.

from

The date, in ISO 8601 format (YYYY-MM-DD), from which to limit the events to.

If not specified, this will default to '1970-01-01T00:00:00.000Z'.

to

The date, in ISO 8601 format (YYYY-MM-DD), to which to limit the events to.

If not specified, this will default to '3000-01-01T00:00:00.000Z'.

resourceid

The resourceid with which to limit the events to.

If not specified, this constraint will be ignored.

example

GET

http://beta.jorum.ac.uk/find/report/views.xml?resourceid=1920

Returns the histogram of views for resourceid=1920 in XML format

GET

http://beta.jorum.ac.uk/find/report/downloads.xml?interval=week&from=2012-09-01&to=2012-09-30

Returns the histogram of downloads for all OERs in the system for September 2012, aggregated by week, in XML format

GET

http://beta.jorum.ac.uk/find/report/uploads.xml

Returns the histogram of uploads for all OERs in the system in XML format, using default argument values

/find/report/views.csv

/find/report/downloads.csv

/find/report/uploads.csv

GET

POST

description

Utility reports for returning histograms of the numbers of views, downloads and uploads, in CSV format.

The reports are equivalent to a date-histogram facet in ElasticSearch.

arguments

interval

The aggregation level to use when calculating the histogram. Valid values are: year, quarter, month, week, day, hour, minute.

If not specified, this will default to 'month'. See also the interval field in the Date Histogram Facet documentation for ElasticSearch.

from

The date, in ISO 8601 format (YYYY-MM-DD), from which to limit the events to.

If not specified, this will default to '1970-01-01T00:00:00.000Z'.

to

The date, in ISO 8601 format (YYYY-MM-DD), to which to limit the events to.

If not specified, this will default to '3000-01-01T00:00:00.000Z'.

resourceid

The resourceid with which to limit the events to.

If not specified, this constraint will be ignored.

example

GET

http://beta.jorum.ac.uk/find/report/views.csv?resourceid=1920

Returns the histogram of views for resourceid=1920 in CSV format

GET

http://beta.jorum.ac.uk/find/report/downloads.csv?interval=week&from=2012-09-01&to=2012-09-30

Returns the histogram of downloads for all OERs in the system for September 2012, aggregated by week, in CSV format

GET

http://beta.jorum.ac.uk/find/report/uploads.csv

Returns the histogram of uploads for all OERs in the system in CSV format, using default argument values

/resources/[resourceid]/report/views.json

/resources/[resourceid]/report/downloads.json

GET

POST

description

Utility reports for returning histograms of the numbers of views and downloads, for a specific resourceid, in JSON format.

The reports are equivalent to a date-histogram facet in ElasticSearch.

arguments

interval

The aggregation level to use when calculating the histogram. Valid values are: year, quarter, month, week, day, hour, minute.

If not specified, this will default to 'month'. See also the interval field in the Date Histogram Facet documentation for ElasticSearch.

from

The date, in ISO 8601 format (YYYY-MM-DD), from which to limit the events to.

If not specified, this will default to '1970-01-01T00:00:00.000Z'.

to

The date, in ISO 8601 format (YYYY-MM-DD), to which to limit the events to.

If not specified, this will default to '3000-01-01T00:00:00.000Z'.

example

GET

http://beta.jorum.ac.uk/resources/1920/report/views.json

Returns the histogram of views for resourceid=1920 in JSON format

GET

http://beta.jorum.ac.uk/resources/1920/report/downloads.json?interval=week&from=2012-09-01&to=2012-09-30

Returns the histogram of downloads for resourceid=1920, for September 2012, aggregated by week, in JSON format

/resources/[resourceid]/report/views.xml

/resources/[resourceid]/report/downloads.xml

GET

POST

description

Utility reports for returning histograms of the numbers of views and downloads, for a specific resourceid, in XML format.

The reports are equivalent to a date-histogram facet in ElasticSearch.

arguments

interval

The aggregation level to use when calculating the histogram. Valid values are: year, quarter, month, week, day, hour, minute.

If not specified, this will default to 'month'. See also the interval field in the Date Histogram Facet documentation for ElasticSearch.

from

The date, in ISO 8601 format (YYYY-MM-DD), from which to limit the events to.

If not specified, this will default to '1970-01-01T00:00:00.000Z'.

to

The date, in ISO 8601 format (YYYY-MM-DD), to which to limit the events to.

If not specified, this will default to '3000-01-01T00:00:00.000Z'.

example

GET

http://beta.jorum.ac.uk/resources/1920/report/views.xml

Returns the histogram of views for resourceid=1920 in XML format

GET

http://beta.jorum.ac.uk/resources/1920/report/downloads.xml?interval=week&from=2012-09-01&to=2012-09-30

Returns the histogram of downloads for resourceid=1920, for September 2012, aggregated by week, in XML format

/resources/[resourceid]/report/views.csv

/resources/[resourceid]/report/downloads.csv

GET

POST

description

Utility reports for returning histograms of the numbers of views and downloads, for a specific resourceid, in CSV format.

The reports are equivalent to a date-histogram facet in ElasticSearch.

arguments

interval

The aggregation level to use when calculating the histogram. Valid values are: year, quarter, month, week, day, hour, minute.

If not specified, this will default to 'month'. See also the interval field in the Date Histogram Facet documentation for ElasticSearch.

from

The date, in ISO 8601 format (YYYY-MM-DD), from which to limit the events to.

If not specified, this will default to '1970-01-01T00:00:00.000Z'.

to

The date, in ISO 8601 format (YYYY-MM-DD), to which to limit the events to.

If not specified, this will default to '3000-01-01T00:00:00.000Z'.

example

GET

http://beta.jorum.ac.uk/resources/1920/report/views.csv

Returns the histogram of views for resourceid=1920 in CSV format

GET

http://beta.jorum.ac.uk/resources/1920/report/downloads.csv?interval=week&from=2012-09-01&to=2012-09-30

Returns the histogram of downloads for resourceid=1920, for September 2012, aggregated by week, in CSV format

Helpful tips

You can see examples of complex search parameters being passed from the main search page to the backend when you look at the parameters copied into the url for the search/report display page - which is how those pages can then be shared via url - the complex object is flattened into the "source" parameter. This is a convenience function for the purposes of saving the url - but it is far cleaner to use the POST endpoint when working directly the the API rather than as a user going via the browser.

The statistical data contained within the index is processed to truncate the IP addresses associated with events, so that the last (class D) address is replaced with an asterisk (*). For example, the address "1.2.3.4" will be stored as "1.2.3.*" in the field "truncated_ip". This field should be treated as a string rather than as an IP address. The related field, "dns", has been removed completely.

Learn more

As the backend is an elasticsearch index, and it already has a great API, and we are exposing most of it to you at the /api/query address, you should check out their docs to learn more about all the cool things you can do with it.

http://www.elasticsearch.org