Calling The API

The DataPortal API for Engagement and Impact Outcomes follows the JASON API Specification (v1.0). The API supports Pagination, Filters and error handling as per the specification. Sparse Fieldsets and Sorting are not supported at this stage.

The Engagement and Impact Outcomes API data is provided in a paginated format. Clients can access this API by specifying a Page Size of up to a maximum of 200 records. The following is an example the URL format :

https://dataportal.arc.gov.au/EI/API/ratings?page[size]=20&page[number]=1&filter=[FILTER_VALUE]

Where

• FILTER_VALUE - filter by Institution Short Name or Field of Research Code

The API URL components must be encoded before calling the API. The following is an example of an encoded URL filtered by Institution.

https://dataportal.arc.gov.au/EI/API/ratings?page%5Bnumber%5D=1&page%5Bsize%5D=20&filter=ANU

The following is an example of an encoded URL filtered by Field of Research

https://dataportal.arc.gov.au/EI/API/ratings?page%5Bnumber%5D=1&page%5Bsize%5D=20&filter=11-BCS

The following is a snippet of a paginated outcomes that has one record per page.

{
    "meta": {
        "requested-page-number": 1,
        "requested-page-size": 1,
        "actual-page-size": 1,
        "total-pages": 1050,
        "total-size": 1050
    },
    "links": {
        "self": "https://dataportal.arc.gov.au/EI/API/ratings?page%5Bnumber%5D=1&page%5Bsize%5D=1",
        "first": "https://dataportal.arc.gov.au/EI/API/ratings?page%5Bnumber%5D=1&page%5Bsize%5D=1",
        "last": "https://dataportal.arc.gov.au/EI/API/ratings?page%5Bnumber%5D=1050&page%5Bsize%5D=1",
        "prev": "https://dataportal.arc.gov.au/EI/API/ratings?page%5Bnumber%5D=1&page%5Bsize%5D=1",
        "next": "https://dataportal.arc.gov.au/EI/API/ratings?page%5Bnumber%5D=2&page%5Bsize%5D=1"
    },
    "data": [
        {
            "type": "ratings",
            "id": "381",
            "attributes": {
                "institution": {
                    "name": "The Australian National University",
                    "short-name": "ANU"
                },
                "assessment-unit": {
                    "code": "01",
                    "name": "Mathematical Sciences"
                },
                "outcomes": [
                    {
                        "year": 2018,
                        "engagement": "Low",
                        "impact": "Medium",
                        "approach-to-impact": "Low"
                    }
                ]
            }
        }
    ]
}

In the snippet above, the meta attribute has the information related to page size, page number and total results. The links attribute has navigation links to other pages and the data attribute has the collection of Engagement and Impact Outcomes.

Troubleshooting

No relevant data in the response

{
    "meta":{...}
    "links": {...}
    "data": []
}

                    

For a specified search, there is no data.

A 'Failed/Unexpected/Unauthorized' response

{
    "links": {
        "self": "https://dataportal.arc.gov.au/EI/API/impact-studies?page%5Bsize%5D=0&page%5Bnumber%5D=1&filter=titlenotfound"
    },
    "errors": [
        {
        "id": "500InternalServerError",
        "status": "InternalServerError",
        "code": "500",
        "title": "SqlException",
        "detail": "The number of rows provided for a FETCH clause must be greater then zero."
        }
    ]
}

{
    "links": {
        "self": "https://dataportal.arc.gov.au/EI/API/impact-studies"
    },
    "errors": [
        {
            "id": "401Unauthorized",
            "status": "Unauthorized",
            "code": "401",
            "title": "UnauthorizedAccessException",
            "detail": "..."
        }
    ]
}

A failed/unexpected/unauthorised response will occur when :

• The URL has invalid attribute values
• The client issues a bad request
• The client is trying to access unauthorized URL or data.
• The client is blocked by ARC