v0.2_api

krug edited this page Oct 19, 2015 · 5 revisions

Table of Contents generated with DocToc

DMAOnline data access API v0.2

Data for display in the dashboard will be extracted from the DMAonline database (currently hosted on lib-ldiv.lancs.ac.uk. The database is PostgreQL and wil be accessed by a REST style interface. This page will be used to document the API calls as they are developed. Each API call is designed to answer the initial 5 use cases as defined by Hardy Schwamm in the Google Docs document here.

Use case 1

As a RDM Manager I’d like to know how many datasets are produced at my institution (with funding from RCUK?)

# Version 0.2 API
GET 'http://lib-ldiv.lancs.ac.uk:8080/dmaonline/v0.2/datasets/<inst_id>'

# to filter by just RCUK funders of datasets

GET 'http://lib-ldiv.lancs.ac.uk:8080/dmaonline/v0.2/datasets/<inst_id>?filter=rcuk'

# to count add the option &count=true as in

GET 'http://lib-ldiv.lancs.ac.uk:8080/dmaonline/v0.2/datasets/<inst_id>?count=true'
GET 'http://lib-ldiv.lancs.ac.uk:8080/dmaonline/v0.2/datasets/<inst_id>?filter=rcuk&count=true'

# to filter by project dates add &date=<project_awarded|project_start|project_end>&sd=<YYYYMMDD>&ed=<YYYYMMDD> e.g.

GET 'http://lib-ldiv.lancs.ac.uk:8080/dmaonline/v0.2/datasets/lancaster?date=project_start&sd=20140101&ed=20141231'

# Other filters
#	&dataset_id=<dataset_id>
#	&project_id=<project_id>
#	&faculty=<faculty_id>
#	&dept=<dept_id>
#	&arch_status=<archived|not_archived|unknown>
#	&location=<internal|external>

# Any combination of filters/options is possible.

where '<inst_id>' is the institution identifier from the 'institutions' data table.

## Use case 2a & 2b combined

# Version 0.2 API

GET http://lib-ldiv.lancs.ac.uk:8080/dmaonline/v0.2/project_dmps/<inst_id>

# to recreate 2a

GET 'http://lib-ldiv.lancs.ac.uk:8080/dmaonline/v0.2/project_dmps/<inst_id>?has_dmp=true'

# and 2b

GET 'http://lib-ldiv.lancs.ac.uk:8080/dmaonline/v0.2/project_dmps/<inst_id>?has_dmp=false&is_awarded=true'

# other filters
#	&dmp_reviewed=<yes|no|unknown>
#	&has_dmp=<true|false>
#	&is_awarded=<true|false
#	&count=true
#	&project_id=<project_id>
#	&faculty=<faculty_id>
#	&dept=<dept_id>

Use case 3

As a RDM manager I'd like to know I'd like to know how many DMPs have been produced at my institution/faculty/department?

# Version 0.2 API

GET http://lib-ldiv.lancs.ac.uk:8080/dmaonline/v0.2/dmps/<inst_id>

# to count add the option &count=true as in

GET 'http://lib-ldiv.lancs.ac.uk:8080/dmaonline/v0.2/dmps/<inst_id>?count=true'

# to filter by project dates add &date=<project_awarded|project_start|project_end>&sd=<YYYYMMDD>&ed=<YYYYMMDD> e.g.

GET 'http://lib-ldiv.lancs.ac.uk:8080/dmaonline/v0.2/dmps/lancaster?date=project_start&sd=20140101&ed=20141231'

# Other filters
#	&project_id=<project_id>
#	&faculty=<faculty_id>
#	&dept=<dept_id>

# Any combination of filters/options is possible.

Use case 4

As a RDM manager I'd like to know how much data storage is actually allocated/ expected allocation / allocation vs real use.

# Version 0.2 API

GET http://lib-ldiv.lancs.ac.uk:8080/dmaonline/v0.2/expected_storage/<inst_id>

# to count add the option &count=true as in

GET 'http://lib-ldiv.lancs.ac.uk:8080/dmaonline/v0.2/expected_storage/<inst_id>?count=true'

# to filter by project dates add &date=<project_awarded|project_start|project_end>&sd=<YYYYMMDD>&ed=<YYYYMMDD> e.g.

GET 'http://lib-ldiv.lancs.ac.uk:8080/dmaonline/v0.2/expected_storage/lancaster?date=project_start&sd=20140101&ed=20141231'

# Any combination of date and count options/filters is possible.

# Other filters
#	&project_id=<project_id>
#	&faculty=<faculty_id>
#	&dept=<dept_id>
#	&dataset_id=<dataset_id>

Use case 5

As a RDM manager I'd like to know how many RCUK funded publications contain data access statements and persistent identifiers?

# Version 0.2 API

GET http://lib-ldiv.lancs.ac.uk:8080/dmaonline/v0.2/rcuk_as/<inst_id>

# to count add the option &count=true as in

GET 'http://lib-ldiv.lancs.ac.uk:8080/dmaonline/v0.2/rcuk_as/<inst_id>?count=true'

# to filter by project or publication dates add &date=<pub.publication_date|proj.project_awarded|proj.project_start|proj.project_end>&sd=<YYYYMMDD>&ed=<YYYYMMDD> e.g.

GET 'http://lib-ldiv.lancs.ac.uk:8080/dmaonline/v0.2/rcuk_as/lancaster?date=proj.project_start&sd=20140101&ed=20141231'

# Any combination of date and count options/filters is possible.

# Other filters are 
#	&faculty=<faculty_id>
#	&dept=<lead_department_id>
#	&project=<project_id>
#	&funder_code=<funder_project_code>
#	&funder=<funder_id>

Institution, Faculty and Department information

# Version 0.2 API

# Get all the institutions DMAonline knows about
GET http://lib-ldiv.lancs.ac.uk:8080/dmaonline/v0.2/institution

# Get institution information for <inst_id>
GET http://lib-ldiv.lancs.ac.uk:8080/dmaonline/v0.2/institution/<inst_id>

# Get the faculties at an institution
GET http://lib-ldiv.lancs.ac.uk:8080/dmaonline/v0.2/faculty/<inst_id>

# Get the faculty information at an institution
GET http://lib-ldiv.lancs.ac.uk:8080/dmaonline/v0.2/faculty/<inst_id>/<faculty_id>

 # Get the departments at an institution
GET http://lib-ldiv.lancs.ac.uk:8080/dmaonline/v0.2/depts/<inst_id>

# Get information about departments in a faculty
GET 'http://lib-ldiv.lancs.ac.uk:8080/dmaonline/v0.2/faculty/depts/<inst_id>?faculty=<faculty_id>'

# Add a new institution
POST http://lib-ldiv.lancs.ac.uk:8080/dmaonline/v0.2/institution?
with parameters 
    &inst_id=<inst_id>
    &name=<Institution name>
    &contact=<Institution contact>
    &email=<email address>
    &phone=<Phone number>
    &cris_sys=<CRIS System>
    &pub=<Publication System>
    &dataset_sys=<Dataset System>

# Add a new faculty
POST http://lib-ldiv.lancs.ac.uk:8080/dmaonline/v0.2/faculty/<inst_id>?
with parameters
    &name=<Faculty Name>
    &abbrev=<Faculty Abbrev>

# Update a faculty
PUT http://lib-ldiv.lancs.ac.uk:8080/dmaonline/v0.2/faculty/<inst_id>/<faculty_id>?
with parameters
    &name=<Faculty Name>
    &abbrev=<Faculty Abbrev>

# Delete a faculty
DELETE http://lib-ldiv.lancs.ac.uk:8080/dmaonline/v0.2/faculty/<inst_id>/<faculty_id>

Dataset accesses

# Version 0.2 API

GET 'http://lib-ldiv.lancs.ac.uk:8080/dmaonline/v0.2/dataset_accesses/<inst_id>?dataset_id=<n>&sd=<YYYYMMDD>&ed=<YYYYMMDD>&summary=true&summary_by_date=true&faculty=<faculty_id>'