Table of Contents - WebAdMIThelp.webadmit.org/.../WebAdMIT_Export_Manager_API.pdf · Table of...

Copyright © 2015 Liaison International, Inc. All Rights Reserved. www.liaison-intl.com

Table of Contents Introduction .......................................................................................................................................................................... 2

WebAdMIT Identities ........................................................................................................................................................ 3

WebAdMIT API Permissions & Keys............................................................................................................................ 4

API Rate Limit ....................................................................................................................................................................... 5

API Methods .......................................................................................................................................................................... 6

1. user_identities ............................................................................................................................................................. 6

Request ............................................................................................................................................................................... 6

Response ............................................................................................................................................................................ 6

2. exports ........................................................................................................................................................................... 8

Request ............................................................................................................................................................................... 8

Response ............................................................................................................................................................................ 8

3. exports (by identity) ................................................................................................................................................. 9

Request ............................................................................................................................................................................... 9

Response ............................................................................................................................................................................ 9

4. export_files (initiate a run) ................................................................................................................................. 10

Request ............................................................................................................................................................................ 10

Response ......................................................................................................................................................................... 10

Callback ........................................................................................................................................................................... 11

5. export_files (check status) .................................................................................................................................. 11

Request ............................................................................................................................................................................ 12

Response ......................................................................................................................................................................... 12

6. export_files (check status in batch) ................................................................................................................. 13

Request ............................................................................................................................................................................ 13

Response ......................................................................................................................................................................... 13

LIAISON API SPECIFICATION DOCUMENT WEBADMIT EXPORT MANAGER API


Introduction The Liaison Export Manager API is designed to allow permissioned users to look up, run, and retrieve export files designed in WebAdMIT’s Export Manager from a direct back-end API. This allows technically-savvy users of WebAdMIT to automate the retrieval of data from WebAdMIT for integration into other on-campus systems. The following key points and conventions are followed in the Export Manager API: This is a REST-based API that will be accessed over a standard HTTP/HTTPS API client library

such as Net::HTTP or Apache HttpClient (all requests must use HTTPS).

Access is controlled via a new “API Access” permission granted in WebAdMIT, and a secure (and refreshable) API key is generated by the user in their account profile in WebAdMIT.

API Access permission is based off of WebAdMIT user identities (described below). All of a user’s exports that can be run via API are owned by one of that user’s identities.

The user’s API key must be passed for every API request, and will be passed in the HTTP header of the request using the “x-api-key” header.

All API requests will be GET or POST actions against RESTful paths.

Response bodies from API calls will be JSON objects and arrays.

The root for all API calls should be https://api.webadmit.org.

https://api.webadmit.org/


WebAdMIT Identities All permissions in WebAdMIT cascade from the concept of “Identities”. What is an “Identity” in WebAdMIT? Each of the selectable items in the standard WebAdMIT account dropdown are considered to be standard admissions-level “identities” – for most universities, this ties to the cohorts of students from each major graduate department:

There are two additional “special” types of identities available in WebAdMIT:

• An “Association User” can access data for all schools in a given Centralized Application Service (e.g. someone at ASPPH would be able to access all data for all schools of public health in SOPHAS, and someone at AACP would be able to access data for all schools of pharmacy in PharmCAS)

• An “Institution User” can access data for all departments & programs at a university implementing UniCAS (this type of user would be able to create a university-wide data export)

In general, configuration entities such as Lists, Exports, Email Templates, and so on in WebAdMIT are “owned” by one of a user’s identities. Every identity that is part of a user’s profile has a name and a unique identifier. These can be retrieved via one of the API calls discussed below in this document. Admissions, Association, and Institutional identities can all be addressed by name or ID in the same manner.


WebAdMIT API Permissions & Keys WebAdMIT user accounts who need access to the Export Manager API need to be given the new “API Access” permission for each of the identities that they have in the WebAdMIT system and that they wish to access via the API. This permission can also be made part of a standard WebAdMIT Work Group.

Users with API Access enabled on at least one of their WebAdMIT identities will be able to generate an API key in their Edit My Account section of WebAdMIT. This API key will then be associated with that user and all of their identities within WebAdMIT. If the key is compromised, it can be regenerated from this screen at any time. This API key must be passed in the HTTP header (key name of “x-api-key”) of all requests to the API, or requests will be rejected.


API Rate Limit WebAdMIT will allow an individual API Key to access the API up to 1,000 times in a 1-hour period. This should be more than sufficient for all normal export running & retrieval, no matter how frequently during the day a user wishes to run their exports. Users can view the current API Rate Limit as well as how many calls an individual API Key has left in the current 1-hour period by viewing the response headers of any API call:


API Methods

1. user_identities Retrieve details on all user identities that are part of a user’s WebAdMIT profile and that have the “API Access” permission assigned to them. The id associated with each identity will not change, and only becomes something new when a new identity is created – for example at the start of a new academic cycle.

Request

Method URL

GET /api/v1/user_identities

Type Params Values

HEAD x-api-key String

Response

Status Response

200 The response is the collection of user identities belonging to the current user that have been given the “API Access” permission: {

"href": "/api/v1/user_identities", "user_identities": [

{ "id": 21530, "type": "Admissions User", "organization": "Demo University School of Public Health", "association": "SOPHAS", "cycle": "2013 - 2014", “institution”: “Demo University”

}, {

"id": 37442, "type": "Admissions User", "organization": "Demo University School of Business", "association": "UniCAS", "cycle": "2014 - 2015", “institution”: “Demo University”

}, {

chrome-extension://fhbjgbiflinjbdggehcddcbncdddomop/api/v1/user_identities


"id": 41542, "type": "Admissions User", "organization": "Demo University College of Health Sciences ", "association": "CSDCAS", "cycle": "2014 - 2015" “institution”: “Demo University”,

} ]

} The response will be similar for users with Association-level identities: {


{ "id": 53021, "type": "Association User", "organization": "", "association": "SOPHAS Admin", “institution”: “”, "cycle": "2013 - 2014"

} ]

} The response will be similar for users with Institution-level identities: {


{ "id": 30154, "type": "Institution User", "organization": "", “association”: “”, "institution": "Demo University Admin", "cycle": "2013 - 2014"

} ]

}




2. exports Retrieve details on all exports (e.g. export templates) that a user has access to across all of their identities. The id returned for each export is the value that needs to be provided in order to run that export.

Request

Method URL

GET /api/v1/exports

Type Params Values


Response

Status Response

200 The response is the collection of exports belonging to any identity in the current user’s WebAdMIT profile, including the List that each export is tied to: {

"href": "/api/v1/exports", "exports": [

{ "id": 29897, "name": "Nightly Banner Export", "list_type": "all", "format": "Comma-Separated Values", "mime_type": "text/csv;charset=iso-8859-1"

}, {

"id": 23696, "name": "Only Matriculants", "list_type": "Matriculating Applicants", "format": "Comma-Separated Values", "mime_type": "text/csv;charset=iso-8859-1"

}, {

"id": 36856, "name": "Foreign Applicants File", "list_type": “Non US Applicants”, "format": "Comma-Separated Values", "mime_type": "text/csv;charset=iso-8859-1"

} ]

}

chrome-extension://fhbjgbiflinjbdggehcddcbncdddomop/api/v1/exports


3. exports (by identity) Retrieve details on all exports (e.g. export templates) that a user has access to within a specific identity. The id returned for each export is the value that needs to be provided in order to run that export.

Request

Method URL

GET /api/v1/user_identities/:user_identity_id/exports

Type Params Values


PARAM user_identity_id Numeric

Response

Status Response

200 The response is the collection of exports belonging to a specific identity in the current user’s WebAdMIT profile, including the List that each export is tied to: {

"href": "/api/v1/user_identities/24567/exports", "exports": [

{ "id": 29897, "name": "Nightly Banner Export", "list_type": "all", "format": "Comma-Separated Values", "mime_type": "text/csv;charset=iso-8859-1"

}, {

"id": 23696, "name": "Only Matriculants", "list_type": "Matriculating Applicants", "format": "Comma-Separated Values", "mime_type": "text/csv;charset=iso-8859-1"

} ]

}


4. export_files (initiate a run) Initiate the background execution of a specific export (e.g. export template). Required parameters are the identity that the export belongs to, and the id of the export that you wish to run. This will create an instance of a running export_file, which is what you can monitor to determine when the export is ready to be downloaded. The id in the response from this call is the handle to that running export_file and what is used in future calls to check on the status of the run. Important note: this id representing the handle to the running instance of the export is not always uniquely generated with each run – if you attempt to run the same export several times in close succession, you will receive back the id of the already-running instance of that export. This is a safeguard to prevent many accidental simultaneous runs of the exact same export – one must finish before a new one can be initiated.

Request

Method URL

POST /api/v1/user_identities/:user_identity_id/exports/:export_id/ export_files

Type Params Values



PARAM export_id Numeric

PARAM callback String (optional callback URL)

Response

Status Response

200 The response is the handle to the running instance of the export the user kicked off, including the id of that export_file (the running instance) and the status of the execution. Possible status values are “Queued”, “In Progress”, “Available”, or “Failed”.

{ "export_files": {

"id": 74780, "href": "/api/v1/exports/86466/export_files/74780", "export_id": 86466,

chrome-extension://fhbjgbiflinjbdggehcddcbncdddomop/api/v1/exports/86466/export_files/74780


"status": "Queued" } }

Callback For requests using the optional “callback” parameter, you should build your request as follows: /api/v1/user_identities/:user_identity_id/exports/:export_id/ export_files?callback=http://someurl.com/your_callback.cgi When the file is ready, WebAdMIT will POST to the callback URL that you specify with the following form POST parameters: export_file[id] export_file[export_id] export_file[status] An example of the body of a POST to a callback when a file is ready is as follows: export_file[id]=99752&export_file[export_id]=123316&export_file[status]=Available This gives you the export_file_id of the file that’s ready for download once it is available (you will use the export_id and the export_file_id POSTed here to form the next API call in item 5 below to actually get the URL to download the now-ready file). We recommend the use of the public RequestBin (http://requestb.in/) service in order to test out how this particular call works.

5. export_files (check status) Retrieve the status of a running export file initiated with the previous POST. Required parameters are the id of the export (e.g. export template) and the id of the running instance of that export (e.g. export file) that you wish to check the status of. You may continue to issue this call over a reasonable polling interval until the file becomes ready for download. Once the status of the file becomes “Available”, a download URL for the file will also be returned from the API. This URL is secure and time-sensitive, expiring less than 30 seconds from when it is issued. It is the expectation that software using this API will immediately download the file once given the URL. The download URL can always be re-generated if it expires by re-calling this method – a new URL will be issued.

http://requestb.in/


Request

Method URL

GET /api/v1/exports/:export_id/export_files/:export_file_id

Type Params Values


PARAM export_id Numeric

PARAM export_file_id Numeric

Response

Status Response

200 The response is the status of the running instance of the export the user is checking on, including the id of that export_file (the running instance), the export id (the export template), the status of the execution, and the actual (time-sensitive) URL to download th file if it is ready. Possible status values are “Queued”, “In Progress”, “Available”, or “Failed”.

{ "export_files": {

"id": 74780, "href": "/api/v1/exports/86466/export_files/74780", "export_id": 86466, "status": "Available", "download_url": "https://webadmit-production.s3.amazonaws.com/export_files/reports/000/074/780/d19d6c0a34b7062c4496530f3d5dbfb_original.txt?AWSAccessKeyId=AKIAIT7746URBGHSHEA&Expires=1425359248&Signature=y2jwr78kbVt44xz%2BfaEnp5dXKU%3D&response-content-disposition=attachment%3B%20filename%3DTest-API-Export.csv&response-content-type=text%2Fcsv%3Bcharset%3Diso-8859-1

} }


https://webadmit-production.s3.amazonaws.com/export_files/reports/000/074/780/d19d6c70a34b7062c4496530f3d5dbfb_original.txt?AWSAccessKeyId=AKIAIT7746UHRBGHSHEA&Expires=1425359248&Signature=y2jwr78kbVt44xz%2BfaEnpD5dXKU%3D&response-content-disposition=attachment%3B%20filename%3DTest-API-Export.csv&response-content-type=text%2Fcsv%3Bcharset%3Diso-8859-1








6. export_files (check status in batch) Closely mimics the “Recent Files” screen in the WebAdMIT application. This call will display all export files that have recently run under a particular identity, and their status. Importantly, the download URL is not displayed in this response as these individual expiring URLs can only be generated by calling for the status of an individual file directly using the previous call. You can use the results of this call and loop through each one to get a download URL for each export file marked as “Available”.

Request

Method URL

GET /api/v1/user_identities/:user_identity_id/export_files

Type Params Values



Response

Status Response

200 The response is the collection of id’s and statuses of the running exports for a specific identity within a user’s WebAdMIT profile:

{ "href": "/api/v1/user_identities/37442/export_files", "export_files": [

{ "id": 74780, "href": "/api/v1/exports/86466/export_files/74780", "export_id": 86466, "status": "Available"

}, {

"id": 77384, "href": "/api/v1/exports/89146/export_files/77384", "export_id": 89146, "status": "Available"

} ] }

chrome-extension://fhbjgbiflinjbdggehcddcbncdddomop/api/v1/user_identities/37442/export_files



Table of Contents - WebAdMIThelp.webadmit.org/.../WebAdMIT_Export_Manager_API.pdf · Table of...

Documents

Transcript of Table of Contents - WebAdMIThelp.webadmit.org/.../WebAdMIT_Export_Manager_API.pdf · Table of...