Overview
Kuali Research has a number of available APIs (Application Programming Interface) that allows institutions to have options of GET, PUT, PATCH, POST, DELETE actions on data in the system. Institutional resources can build out integrations to and from Kuali Research using these rest APIs and below outlines the available documentation and instructions on setting up the necessary authentication to access and how to use.
NOTE: Our APIs are robust and have general documentation but it is not completely comprehensive. Please be aware that technical resources are required to utilize and a knowledge of the database structure in the module itself. Issues/questions that arise when using can be asked via support ticket and we will attempt to assist or provide solutions.
API Documentation
Documentation for APIs can be found in your hosted environment URLs as specified below for each functional area. If not a hosted school you can also find in the general sandbox environment (https://greendale.kuali.co) using the same logic described below. This documentation lays out the REST APIs that are available to facilitate integrations with other University systems. Current APIs should be accessed using a Kuali User API Key.
- Sponsored Programs: customer url with /res/apidocs at the end (i.e https://greendale.kuali.co/res/apidocs)
- Protocols: customer url with /protocols/docs at the end (i.e https://greendale.kuali.co/protocols/docs)
- COI: api documentation still in progress
- Kuali Users/Groups: https://developers.kuali.co/
Using APIs
Kuali Research APIs used for integration with local systems are secured industry standard JWT API tokens, which are unique to each hosted instance. You can generate the API keys for your hosted instances via the kuali users interface in /users (i.e. https://greendale.kuali.co/users). Keys are unique per environment (production, sandbox, etc). More information on generating API keys can be found in the Technical - Setting Up API Key and Maintenance Notifications article.
Once generated you will need to use that in API tool (explained below) to connect to the Kuali Research database.
The API will respond with a status codes that can be used to identify the results of a request. Example:
200 - Successful. The request was successfully processed.
400 - Bad Request. Invalid data
401 - Unauthorized. Invalid token.
404 - The requested item was not found.
500 - Internal server error. Unexpected error.
API Examples
All of the below examples will use the command line tool cURL for brevity and because it is commonly already installed on most UNIX-based systems. The tools Postman and Insomnia are also great and feature rich if you prefer to use something with a GUI. Most of these examples will be written as Bash scripts and may use the command line tool jq for parsing and manipulating JSON responses. These are just a few possible use cases to give you a better understanding of using the APIs but you could utilize all the available API fields with desired filters/logic depending on your needs.
Closing out an Award
Step 1: Retrieve the active version of an award based on its award number:
# Get the ACTIVE version of a given award
AWARDS=$(curl -XGET 'https://greendale.kuali.co/res/award/api/v1/awards/?awardNumber=000294-00001&awardSequenceStatus=ACTIVE' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1dWlkIjoiNWJlZmUxNWQtOTE5OS00ODYyLTk0ODctODcyYTYxYTYyNDczIiwiaWF0IjoxNjAzMjk0Nzg4fQ.oEybx-w-SrWTqtOExE-kJnhp9YZiwbmAZ_LkTd2CMv8' \
-H 'Content-Type: application/json');
echo $AWARDS;
# [
# {
# "awardId": 15936
# "awardNumber": "000294-00001",
# "sequenceNumber": 1,
# "sponsorCode": "000340",
# "statusCode": 1,
# ...
# }
# ]
# Extract the Award ID of the award in the returned JSON paylaod
AWARD_ID=$(echo $AWARDS | jq -r '.[0].awardId');
# Update the status of the award version with AWARD_ID to CLOSED (statusCode = 5)
curl -XPATCH "https://greendale.kuali.co/res/award/api/v1/awards/${AWARD_ID}" \
--data '{ "statusCode": "5" }' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1dWlkIjoiNWJlZmUxNWQtOTE5OS00ODYyLTk0ODctODcyYTYxYTYyNDczIiwiaWF0IjoxNjAzMjk0Nzg4fQ.oEybx-w-SrWTqtOExE-kJnhp9YZiwbmAZ_LkTd2CMv8' \
-H 'Content-Type: application/json';
# Should return status 204 No Content-- the update was made successfully
Update Institutional Proposal Status to Rejected
Using PATCH to update status code using proposal id (10 - which is the primary key). We need to retrieve the proposal to identify the proposal id based on any other criteria (say proposal number) since proposal id is the key internal which associated with this proposal. If you know the proposal id you can use the below:
curl -X PATCH --data '{"statusCode": 4}' -H "content-type: application/json" -H "Authorization: Bearer <<api_key>>" https://greendale.kuali.co/res/instprop/api/v1/institutional-proposals/10
If you don't know the proposal id you will need to find it first; below outlines that path and then updating the status based on the id you find:
# Get proposal PROPOSAL=$(curl -X GET 'https://greendale.kuali.co/res/instprop/api/v1/institutional-proposals?proposalNumber=00000009&proposalSequenceStatus=ACTIVE' \ -H 'Authorization: Bearer <<api_key>>' \ -H 'Content-Type: application/json'); # Extract the proposal ID PROPOSAL_ID=$(echo $PROPOSAL | jq -r '.[0].proposalId'); #Update Status curl -X PATCH --data '{"statusCode": 4}' -H "content-type: application/json" -H "Authorization: Bearer <<api_key>>" https://greendale.kuali.co/res/instprop/api/v1/institutional-proposals/${PROPOSAL_ID}
Find Person Records with a Filter
You can retrieve person information from the Person table entry for an individual or individuals using the below example curl with user admin specified:
curl -X GET -H "Authorization: Bearer <<api_key>>" https://greendale.kuali.co/res/research-sys/api/v1/principals?principalName=admin
The response will be as follows:
[{"password":null,"active":true,"principalId":"admin","principalName":"admin","entityId":"1100","_primaryKey":"admin"}]
Find Kuali Users with a Filter (users found in /users)
You can also use APIs to access kuali user information found in the /users area of your application (i.e. greendale.kuali.co/users). This kuali user is used in conjunction with the Person record on the Sponsored Programs monolith side and independently on the compliance modules. If you want to query information for a particular user in kuali users you could use below curl with user admin specified:
curl -X GET -H "Authorization: Bearer <<api_key>>" https://greendale.kuali.co/api/v1/users?schoolId=admin
This would return with the below response:
[{"updatedBy":{"id":"5c50c28432e84d65873174d0","impersonatedBy":null},"role":"admin","systemNotifications":"all","approved":true,"active":true,"products":[],"updatedAt":1563460706839,"createdAt":1548796146489,"name":"admin, admin","firstName":"admin","lastName":"admin","username":"admin","schoolId":"admin","email":"res-admin@kuali.co","groupId":"5c50c2a132e84d4c5031756f","phone":"","scopesCm":null,"ssoProps":null,"id":"5c50c0f232e84de69c317497","mongoId":"5c50c0f232e84de69c317497","displayName":"admin, admin","ssoId":null}]
Another example use case, if you wanted to find all kuali users with a null School ID you could use the below curl:
curl -X GET -H "Authorization: Bearer <<api_key>>" https://greendale.kuali.co/api/v1/users?schoolId=null
Get Sponsors
To retrieve sponsor information from the Sponsor table in the Sponsored Programs monolith you could use the below curl example:
curl -X GET -H "Authorization: Bearer <<api_key>>" https://<<your_domain>>.kuali.co/res/research-common/api/v1/sponsors
Get Sponsors with Limit/Paging incorporated:
curl -X GET -H "Authorization: Bearer <<api_key>>" https://<<your_domain>>.kuali.co/res/research-common/api/v1/sponsors?_startindex=0'&'_limit=2
Get Sponsors using a filter condition:
curl -X GET -H "Authorization: Bearer <<api_key>>" https://<<your_domain>>.kuali.co/res/research-common/api/v1/sponsors?sponsorCode=000500
Additional information in the header to support paging:
x-kuali-paging-limit: 2
x-kuali-paging-start-index: 0
x-kuali-paging-total: 5493
The above curl will result in the below sample response:
[{"cageNumber":null,"acronym":"NSF","dodacNumber":null,"rolodexId":11745,"postalCode":"22230","sponsorName":"National Science Foundation","active":true,"ownedByUnit":"000001","customerNumber":null,"sponsorCode":"000500","sponsorTypeCode":"0","dunsPlusFourNumber":null,"auditReportSentForFy":null,"dunningCampaignId":null,"countryCode":"USA","dunAndBradstreetNumber":"074811803","createUser":"quickstart","state":"VA","_primaryKey":"000500"}]
API Limiting
The Kuali Research suite APIs include limits on the maximum number of results they return, as well as having the ability to page through large result sets. To maintain compatibility with existing integrations, the response format will not be changing to accomodate the addition of paging but new response headers will be added to indicate the caller's position in the result set:
X-Kuali-Paging-Start-Index: The current index of the results being returned.
X-Kuali-Paging-Limit: The upper limit on the number of results returned.
X-Kuali-Paging-Total: The total number of results in the entire result set.
All GET MULTIPLE APIs will also be updated to accept the following query parameters to support paging through the result set:
- _startIndex: The first index of the result set to be retrieved (starting at 0).
- _limit: The number of results to return. Defaults to the limit defined by the
REST_ENDPOINT_LIMIT_DEFAULT parameter controls this limit (default is 500) and should not be adjusted without first checking with Kuali support. If you have requests larger than 500 you will need to update to page through results over multiple requests.
Related Documentation
APIs can be used in a number of places in Kuali Research like HR or Financial system integrations. More information on these specific integrations using our APIs can be found in the below articles:
Comments
0 comments
Article is closed for comments.