Articles in this section

See more

Technical - Kuali Research APIs for Beginners

Avatar
Rachel Teki
  • Updated
Follow

Overview

APIs, or application programming interface, are a technical tool that can be used to directly access the information in your Kuali Research database without having to log into Kuali. This article will explain how to get started with APIs, including steps for testing APIs in your lower environments. 

Using an API Client

While highly technical users can use APIs directly, an API client is a third-party tool that can be helpful for beginners to get familiar with the right formatting, etc. As illustrated in the below graphic, an API client  builds a bridge to your data that is standardized and user-friendly. Some examples are Postman, Insomnia, Swagger, and SOAPUI.

When working with APIs, you are going to enter the request information to tell the system what record you're looking for, and it will display the results in the response.

Parts of the Request

HTTP Methods (see yellow box in below screenshot): The HTTP method indicates the type of action that you want to perform in the API.

  • View-only access: safe to use in any environment
    • GET
  • Edit access: always test and confirm in STG before applying in PRD
    • POST: create a new entry
    • PUT: fully update an existing entry
    • PATCH: partially update an existing entry
    • DELETE: delete an existing entry

Endpoint (see green box in below screenshot): This tells the system which record or table you're looking for and will look like a URL. The endpoints that are available for SP are documented at https://{{environment}}.kuali.co/res/apidocs

Parameter (optional) (see orange box in below screenshot): Parameters allow you to filter the results, such as looking for all proposals for a specific sponsor or all award with a specific activity type code. 

API key (see blue box in below screenshot): An API key is similar to a password that allows you to access the database. Each key is associated with a specific user to ensure they have the correct permissions to view and edit the records. To generate your API key, log into your desired Kuali Research environment and go to Users. Click on the API Keys tab and click Create Key. Copy the key that displays and insert it into the Authorization section using the Auth Type of "Bearer Token". This is the only time you can retrieve the key. If you lose it you will need to revoke that key and generate a new one. Keys are unique per environment (PRD, STG, and SBX), so you will need to generate new key for each environment. 

Body (see pink box in below screenshot)(optional): If you want to edit the information in the database, you would list the corrected information in the body of the request. Click on the Body section and select "raw" and "JSON".

Parts of the Response

Status (see red box in below screenshot): The status code will indicate if the request was successful, or if it encountered issues that need to be fixed. 

Body (see purple box in below screenshot) (optional): If you want to view the information in the database, the body of the response should list that information. 

APIs are a powerful tool that can modify your data. When editing a record using the API, best practice is to test and confirm in your STG environment first before applying in your PRD environment using the following steps:

Steps to follow

  1. Test and confirm in STG first
    1. Generate the STG API key and insert in Authorization section
    2. Run GET
    3. Copy body from GET response, paste into body of request, and make desired edits
    4. Run PUT
    5. Run GET to verify edits. If correct, copy GET response to use in Step 2.3
  2. Once verified, apply in PRD
    1. Generate the PRD API key and insert in Authorization section.
    2. Update endpoint to PRD.
    3. Paste the GET response from Step 1.5 in STG into request.
    4. Run PUT. 

Available Endpoints

Documentation for APIs can be found in your hosted environment URLs as specified below for each functional area

Related articles

Comments

0 comments

Article is closed for comments.