Fetching statistics reports via the API

The API can provide a mechanism to query the reporting data. This gives a flat report in CSV format you can use in analysis tools such as Tableau, Power BI and others.

Prerequisites

• The optional reports API functionality to be enabled for your organisation - your account manager will be happy to discuss pricing with you
• An API Key from the domain organisation or sub-organisation the reports will cover.
  • The key will need either the reports API permission (recommended) or the full access permission.
• A basic practical knowledge of APIs and coding

Procedure

Perform a GET request to the following URL:

https://reports.openathens.net/api/v1/example.org/report?type=<type>&from=<from>&to=<to>&by=<by>[&resource=<resource>][&scope=<scope>][&andBy=<andBy>][&granularity=<granularity>]

Where example.org is your OpenAthens API name and:

The maximum date range you can query depends on the granularity, as follows:

Response codes

Response payload

Since reports can take some time to run, the response is an application/vnd.eduserv.iam.reports.task-v1+json object containing a href to the task status. Your application will need to monitor this until the task completes (20s is a reasonable wait time to code).

Once the task is complete, the object will have a status of FINISHED and a percentComplete of 100, and a link to the report.  

Example

Request:
GET https://reports.openathens.net/api/v1/example.org/report?type=RESOURCE_USAGE&from=2020-01&to=2020-01&by=RESOURCE&scope=ALL_ORGANISATIONS
Authorization: OAApiKey <api-key>
Response:
HTTP/1/1 200 OK
Content-Type: application/vnd.eduserv.iam.reports.task-v1+json

{
    "percentComplete": 0,
    "status": "RUNNING",
    "links": [
        {
            "href": "https://reports.openathens.net/api/v1/example.org/task/a11b5fff-6170-38e3-b4bb-560bee3e6985",
            "rel": "SELF",
            "type": "application/vnd.eduserv.iam.reports.task-v1+json",
            "method": "get"
        }
    ],
    "id": "a11b5fff-6170-38e3-b4bb-560bee3e6985"
}

When finished, the response will have updated to include a link to the report

Request:
GET https://reports.openathens.net/api/v1/example.org/task/a11b5fff-6170-38e3-b4bb-560bee3e6985
Authorization: OAApiKey <api-key>
Response:
HTTP/1/1 200 OK
Content-Type: application/vnd.eduserv.iam.reports.task-v1+json

{
    "percentComplete": 100,
    "status": "FINISHED",
    "links": [
        {
            "href": "https://reports.openathens.net/api/v1/athens/report/a11b5fff-6170-38e3-b4bb-560bee3e6985",
            "rel": "DOWN",
            "type": "application/vnd.eduserv.iam.reports.report-v1+json",
            "method": "get"
        }
    ],
    "id": "a11b5fff-6170-38e3-b4bb-560bee3e6985"
}

Report format

The downloaded report will be a CSV file (MIME type text/csv) with these headings:

Domain,Organisation number,Organisation name,DateTime,<by>,[<andyby>,]Count

where:

• Domain is your API name (as per the request). This will be constant for the report
• Organisation number is the numeric identifier of the organisation (or sub-organisations where scope=ALL_ORGANISATIONS in the request). See below if you have more than one in the report.
• DateTime is the date/time of the record as yyyy-MM for monthly granularity, yyyy-MM-dd for daily, and yyyy-MM-ddTHH:mmZ for hourly (ISO 8601)
• <by> will be replaced by RESOURCE, GROUPS, PERMISSION_SETS, or ATTRIBUTE:<targetname> as per the request
• <andBy> (where present) will similarly be replaced by the secondary breakdown identifier
• Count will be the number of transfers
  
  

Anything to watch out for?

When using ATTRIBUTE:<target name> with the by or andBy parameters, the target name of the attribute must be normalised to lower case of the request will fail with a 400 error

Daily granularity reports are inclusive of the start and end date

API keys respect the hierarchy of the organisation structure - if you only want data from a specific sub-organisation or branch, create the API key under the relevant sub-organisation

Querying certain dates will produce an error:

• dates before your organisation joined OpenAthens
• dates before January 2018
• dates more than 48 months in the past