Skip to content
This repository has been archived by the owner on Apr 21, 2019. It is now read-only.

v0.3_api

Jump to bottom
John Krug edited this page Jul 21, 2016 · 30 revisions

Table of Contents generated with DocToc

DMAOnline data access API v0.3

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

The base URL is http://lib-ldiv.lancs.ac.uk:8080/dmaonline/v0.3

This will be via SSL for any production service.

Open APIs

Accessible without any authorisation or api_key.

DMAOnline Aggregate information APIs

These provide aggregate information about the information held in DMAOnline. Intended to be used on the DMAOnline dashboard home page prior to an institutional login. They provide a simple count of the corresponding object within DMAOnline.

/o/o_count_institutions
/o/o_count_faculties
/o/o_count_departments
/o/o_count_dmps
/o/o_count_publications
/o/o_count_datasets
/o/o_count_dataset_accesses
/o/o_datacite_id

DMAOnline authorisation

This provides a list of institution identifiers and names that are known within DMAOnline.

/o/o_inst_list

This is used to retrieve the api_key for an institution.

/o/<inst_id>/o_get_api_key?user=<username>&passwd=<passwd>

where 'inst_id' has been retrieved by 'o_inst_list', 'username' is a registered DMAOnline user and 'passwd' is a sha224 hash in hex format of the user password. For example:

/o/d_lancaster/o_get_api_key?user=krug&passwd=de76c3e567fca9d246f5f8d3b2e704a38c3c5e258988ab525f941db8

APIs requiring an api_key

/c/<inst_id>/<api_key>/faculties_departments

Retrieves a list of faculties and departments.

'Canned' query APIs

These are intended to answer specific use case questions. They are all of the form:

/c/<inst_id>/<api_key/<query_identifier> 

/c/<inst_id>/<api_key>/datasets
/c/<inst_id>/<api_key>/project_dmps
/c/<inst_id>/<api_key>/project_dmps_modifiable
/c/<inst_id>/<api_key>/dmp_status
/c/<inst_id>/<api_key>/storage
/c/<inst_id>/<api_key>/rcuk_as
/c/<inst_id>/<api_key>/dataset_accesses
/c/<inst_id>/<api_key>/publications_editor
/c/<inst_id>/<api_key>/advocacy_events
/c/<inst_id>/<api_key>/persons

Optional parameters

All (apart from those querying modifiable columns)

faculty=<faculty_id>
dept=<dept_id>

datasets

count=true # Just count the number of results as opposed to returning the data
date=<project_awarded|project_start|project_end>&sd=<YYYYMMDD>&ed=<YYYYMMDD>
filter=rcuk # Only include RCUK datasets in the result
project_id=<project_id>
dataset_id=<dataset_id>
arch_status=<archived|not_archived|unknown>
location=<internal|external>

project_dmps

count=true
date=<project_awarded|project_start|project_end>&sd=<YYYYMMDD>&ed=<YYYYMMDD>
dmp_reviewed=<yes|no|unknown>
has_dmp=<true|false>
is_awarded=<true|false
project_id=<project_id>

dmp_status

count=true
date=<project_awarded|project_start|project_end>&sd=<YYYYMMDD>&ed=<YYYYMMDD>
project_id=<project_id>
has_dmp==<true|false>
dmp_state=
dmp_status=
dmp_reviewed=<yes|no|unknown>

storage

count=true
date=<project_awarded|project_start|project_end>&sd=<YYYYMMDD>&ed=<YYYYMMDD>
project_id=<project_id>
dataset_id=<dataset_id>

rcuk_as

count=true
date=<publication_date|project_awarded|project_start|project_end>&sd=<YYYYMMDD>&ed=<YYYYMMDD>
project_id=<project_id>
funder_code=<funder_project_code>
funder=<funder_id>

dataset_accesses

dataset_id=<dataset_id>
sd=<YYYYMMDD>&ed=<YYYYMMDD>
summary=true
summary_by_date=true
summary_totals=true

publications_editor

count=true
date=<publication_date>&sd=<YYYYMMDD>&ed=<YYYYMMDD>
publication_id=<publication_id>
funder_compliant=<y|n|partial>
data_access_statement=<y|n|partial|no_fulltext>

persons

count=true
date=<cris_load_date|cris_mod_date>
person_id=<person_id>
email=<email_address>
last_name_like=<string>

Working with advocacy events

advocacy_session_types

An advocacy event/session can be one of a limited number of types:

List advocacy session types
/luve_u/<api_key>/advocacy_session_types
Create an advocacy session type

By a HTTP POST with JSON form data to:

/luve_u/<api_key>/advocacy_session_types

for example with a json payload file named advocacy_session_types.json as:

[
    {
        "ast_name": "A very different Library Training Session",
        "inst_id": "luve_u"
    }
]

then the following curl request would create a new advocacy session type:

curl -F "data=@advocacy_session_types.json" \
    -H "Content-Type: multipart/form-data" -X POST \
    'http://<hostname>:<port>/dmaonline/v0.3/<inst_id>/<api_key>/advocacy_session_types'

or

curl -H "Content-Type: application/json' -X POST -d '<some_json>' \
    'http://<hostname>:<port>/dmaonline/v0.3/<inst_id>/<api_key>/advocacy_session_types'

The payload file could contain more than one new advocacy session type.

Modify an advocacy session type

By a HTTP PUT with JSON form data to:

/luve_u/<api_key>/advocacy_session_types

for example with a json payload file named advocacy_session_types_update.json as:

[
    {
        "pkey:ast_id": 8,
        "ast_name": "A very, very different Library Training Session",
        "inst_id": "luve_u"
    }
]

then the following curl request would update an advocacy session type:

curl -F "data=@advocacy_session_types_update.json" \
    -H "Content-Type: multipart/form-data" -X PUT \
    'http://<hostname>:<port>/dmaonline/v0.3/<inst_id>/<api_key>/advocacy_session_types'

or

curl -H "Content-Type: application/json' -X PUT -d '<some_json>' \
    'http://<hostname>:<port>/dmaonline/v0.3/<inst_id>/<api_key>/advocacy_session_types'

The primary key is specified in the data payload file rather than as part of the REST URI. This is so multiple updates can be specified per payload file. This may be subject to review, it may be better to stick to more RESTful like URIs.

Delete an advocacy session type
curl -X DELETE \
    'http://<hostname>:<port>/dmaonline/v0.3/<inst_id>/<api_key>/advocacy_session_types/ast_id/<ast_id>'

advocacy_events

count=true
event_id=<event_id>
date=session_date
session_type=<integer>
person_id=<integer>
List advocacy events
/c/luve_u/<api_key>/advocacy_events
Create an advocacy event

By a HTTP POST with JSON form data to:

/c/luve_u/<api_key>/advocacy

for example with a json payload file named advocacy.json as:

[
    {
        "department_id": 9,
        "faculty_id": 2,
        "inst_id": "luve_u",
        "notes": "Reviewed draft DMP (jhk_test)",
        "num_participants": 1,
        "session_content": "DMP",
        "session_date": "2016-07-01",
        "session_type": 2
    }
]

then the following curl request would create a new advocacy session type:

curl -F "data=@advocacy.json" \
    -X POST \
    'http://<hostname>:<port>/dmaonline/v0.3/<inst_id>/<api_key>/advocacy'

or

curl -d "<a_json_string>" \
    -H "Content-Type: application/json" -X POST \
    'http://<hostname>:<port>/dmaonline/v0.3/<inst_id>/<api_key>/advocacy'
Modify an advocacy event

By a HTTP PUT with JSON form data to:

/luve_u/<api_key>/advocacy

for example with a json payload file named advocacy_update.json as:

[
    {
        "pkey:event_id": 8,
        "inst_id": "luve_u",
        "num_participants": "23"
    }
]

then the following curl request would update an advocacy session type:

curl -F "data=@advocacy_update.json" \
    -X PUT \
    'http://<hostname>:<port>/dmaonline/v0.3/<inst_id>/<api_key>/advocacy'
Delete an advocacy event
curl -X DELETE \
    'http://<hostname>:<port>/dmaonline/v0.3/<inst_id>/<api_key>/advocacy/event_id/<event_id>'
Add people to an advocacy event

By a HTTP POST with JSON form data to:

/c/luve_u/<api_key>/map_advocacy_person

for example with a json payload file named map_advocacy_person.json as:

[
    {
        "event_id": 11,
        "inst_id": "luve_u",
        "person_id": 1
    },
    {
        "event_id": 11,
        "inst_id": "luve_u",
        "person_id": 2
    }
]

then the following curl request would create assign people to advocacy events:

curl -F "data=@map_advocacy_person.json" \
     -X POST \
    'http://<hostname>:<port>/dmaonline/v0.3/<inst_id>/<api_key>/map_advocacy_person'
Remove a person from an advocacy event
curl -X DELETE \
    'http://<hostname>:<port>/dmaonline/v0.3/<inst_id>/<api_key>/map_advocacy_person/event_id/<event_id>/person_id/<person_id>'

'Canned' PUT API's

/c/<inst_id>/<api_key>/project_dmps

When a http method of PUT is used a row within project_dmps can be updated. A project_id must be specified as the primary index and the values to be changed submitted. The columns that are modifiable can be retrieved with the api call /c/<inst_id>/<api_key>/project_dmps?modifiable=true.

/c/<inst_id>/<api_key>/storage

When a HTTP method of PUT is used a row within storage can be updated. A project_id must be specified as the primary index and the values to be changed submitted. The columns that are modifiable can be retrieved with the API call /c/<inst_id>/<api_key>/storage?modifiable=true. new expected_storage amount and the inst_storage_platform_id and the project_id must be specified in this call.

For example

/c/<inst_id>/<api_key>/storage?project_id=1&inst_storage_platform_id=hcp&expected_storage=10000

/c/<inst_id>/<api_key>/publications_editor

When a HTTP PUT method is used a row within publications_editor can be updated. A publication_id must be specified as the primary index and the values to be changed submitted. The columns that are modifiable can be retrieved with the API call /c/<inst_id>/<api_key>/publications_editor?modifiable=true

Example session

curl -s 'http://lib-dmao.lancs.ac.uk:8090/dmaonline/v0.3/o/o_count_institutions'
[{"count":1}]
curl -s 'http://lib-dmao.lancs.ac.uk:8090/dmaonline/v0.3/o/o_count_faculties'
[{"count":4}]
curl -s 'http://lib-dmao.lancs.ac.uk:8090/dmaonline/v0.3/o/o_count_departments'
[{"count":11}]
curl -s 'http://lib-dmao.lancs.ac.uk:8090/dmaonline/v0.3/o/o_count_dmps'
[{"count":9}]
curl -s 'http://lib-dmao.lancs.ac.uk:8090/dmaonline/v0.3/o/o_count_publications'
[{"count":7}]
curl -s 'http://lib-dmao.lancs.ac.uk:8090/dmaonline/v0.3/o/o_count_datasets'
[{"count":13}]
curl -s 'http://lib-dmao.lancs.ac.uk:8090/dmaonline/v0.3/o/o_count_dataset_accesses'
[{"access_type":"metadata","count":3328},{"access_type":"data_download","count":3328}]
curl -s 'http://lib-dmao.lancs.ac.uk:8090/dmaonline/v0.3/o/o_inst_list'
[{"name":"Lancaster University","inst_id":"d_lancaster"}]
curl -s 'http://lib-dmao.lancs.ac.uk:8090/dmaonline/v0.3/o/d_lancaster/o_get_api_key?user=aac&passwd=aad8b4393cadaef52ce00a7bbc6711298b7de27a3dc248d01fc38272'
[{"api_key":"f8071b41d994e4557591bb3d3a148707820d7ee1e0310196e70ae8aa"}]
curl -s 'http://lib-dmao.lancs.ac.uk:8090/dmaonline/v0.3/c/d_lancaster/f8071b41d994e4557591bb3d3a148707820d7ee1e0310196e70ae8aa/project_dmps_modifiable' | pp_json
[
    {
        "c_vals": "true|false",
        "c_name": "has_dmp"
    },
    {
        "c_vals": "yes|no|unknown",
        "c_name": "has_dmp_been_reviewed"
    },
    {
        "c_vals": "integer",
        "c_name": "dmp_id"
    }
]
curl -s 'http://lib-dmao.lancs.ac.uk:8090/dmaonline/v0.3/c/d_lancaster/f8071b41d994e4557591bb3d3a148707820d7ee1e0310196e70ae8aa/project_dmps_view?project_id=1' | pp_json
[
    {
        "has_dmp_been_reviewed": "no",
        "dmp_id": "null",
        "project_acronym": "null",
        "has_dmp": false,
        "project_awarded": "2012-12-01",
        "project_date_range": "[2013-01-01,2017-12-31)",
        "inst_url": "null",
        "lead_faculty_abbrev": "FST",
        "lead_dept_abbrev": "",
        "description": "null",
        "project_start": "2013-01-01",
        "project_name": "Intractable Likelihood: New Challenges From Modern Applications (iLike)",
        "lead_dept_name": "Mathematics and Statistics",
        "lead_faculty_name": "Faculty of Science and Technology",
        "mod_date": "2015-11-03 12:40:35.701549",
        "inst_id": "d_lancaster",
        "is_awarded": true,
        "project_id": 1,
        "lead_faculty_id": 2,
        "institution_project_code": "MAA7754",
        "funder_project_code": "EP/K014463/1",
        "load_date": "2015-11-03 11:45:47.829116",
        "project_end": "2017-12-31",
        "lead_department_id": 5
    }
]
curl -X PUT -s 'http://lib-dmao.lancs.ac.uk:8090/dmaonline/v0.3/c/d_lancaster/f8071b41d994e4557591bb3d3a148707820d7ee1e0310196e70ae8aa/project_dmps_view_put?project_id=1&has_dmp_been_reviewed=yes' | pp_json
{
    "1": {
        "has_dmp_been_reviewed": "yes",
        "dmp_id": "null",
        "project_acronym": "null",
        "has_dmp": false,
        "project_awarded": "2012-12-01",
        "project_date_range": "[2013-01-01,2017-12-31)",
        "inst_url": "null",
        "lead_faculty_abbrev": "FST",
        "lead_dept_abbrev": "",
        "description": "null",
        "project_start": "2013-01-01",
        "project_name": "Intractable Likelihood: New Challenges From Modern Applications (iLike)",
        "lead_dept_name": "Mathematics and Statistics",
        "lead_faculty_name": "Faculty of Science and Technology",
        "mod_date": "2015-11-03 12:40:35.701549",
        "inst_id": "d_lancaster",
        "is_awarded": true,
        "project_id": 1,
        "lead_faculty_id": 2,
        "institution_project_code": "MAA7754",
        "funder_project_code": "EP/K014463/1",
        "load_date": "2015-11-03 11:45:47.829116",
        "project_end": "2017-12-31",
        "lead_department_id": 5
    },
    "affected_rows": 1
}

Logo

Data access API v0.2

Data access API v0.3

Clone this wiki locally