This tutorial will help you create your first API request through our API sandbox functionality.
Please note, using the Sandbox functionality runs API commands against your live site's data.
Your api sandbox URL will be: http://api.one45.com
Your school has a designated API keyholder. Only people with the
keyholder permission can register applications and effectively grant access
to One45 APIs. Before continuing, contact your school's keyholder and ask
them to register an application for you. They will provide you with a client
key and client secret to use for this tutorial. If you do not know who your
API keyholder is, please contact api@one45.com.
If you are a keyholder, you can grant access to your school's API by
registering an 'application' which generates a client key and secret.
First, log into the One45 system and navigate to
"Setup" > "Developers" > "API Portal".
Click on "Manage Applications" from the menu along the top of
the page. Locate the form on the top left side of the page,
fill in your application name and description, then click on
"Register application".
You'll see a new entry appear with the application name and
description associated with a new client key and client secret.
Privately share this key/secret pair with the individual
requesting API access. They will need this information to
generate API requests. Note - the client key and client secret
should be treated like a password.
Once you have obtained your client key and secret, store them in a
secure place - these should be treated like a username and password.
Now you're ready to generate your first API request. Log in to the
One45 system, navigate to "Setup" > "Developers" > "API Portal" and
click on the "View Reference Docs" button.
To make an API request, you first need to ask the system for an
access token. To do
this, scroll down to the section entitled "/token"
(pointer 1 in figure A).
Figure A - The "Token" section in the 'REST API' documentation.
Next, click on "POST /public/api/v1/token/generate" (pointer 2 in figure A).
Click "Try it out" (pointer 3 in figure A).
Now, enter your client key and client secret in their respective fields (indicated with arrows in figure B).
Figure B - The "/public/api/v1/token/generate" endpoint in the 'REST API' documentation
Now, click "Execute" (indicated with arrow in figure B).
You should receive a "200 OK" response header with an access token in
the "Response Body" (indicated in figure C). Copy this token.
If you don't get a "200 OK" response, ensure you copied your
key and secret into the right fields in step 5. If that still
doesn't work, contact your API Keyholder to ensure they relayed
the correct key and secret to you.
Figure C - Sample response from the "POST /public/api/v1/token/generate" endpoint
You can now scroll back to the top of the page and click "Authorize" (see figure D).
Figure D - Demo on how to save your generated access token
In the modal that appears, enter "Bearer " followed by your access token (see figure D).
Click "Authorize" once you have entered the access code, then click "Close" (see figure D).
You now get to choose an API resource you'd like to make a request
with. Select one from this same page as the "/token" resource. In this
tutorial, we'll pick the "/forms" resource (pointer 1 in figure E). Click on
"GET /api/v1/forms" (pointer 2 in figure E).
Figure E - The "GET /api/v1/forms" endpoint in the 'REST API' documentation.
Like before, click on "Try it out" (pointer 3 in figure E).
Click on "Execute" (indicated in figure F). You should momentarily receive a "200 OK" response header.
Figure F - The "GET /api/v1/forms" endpoint in the 'REST API' documentation.
If everything went accordingly, you should now see a JSON response of
forms existing in your sandbox system under the "Response body"
(indicated in figure G).
Figure G - Sample response from the "GET /api/v1/forms" endpoint
Congratulations! You've completed your first One45 API request.
Tutorial #2 - Programming an API request
While the initial tutorial is great for playing around with the APIs through
our sandbox, this tutorial shows you how to make API calls directly in your code.
Please familiarize yourself with the concepts and examples in the
"Getting Started" tutorial before continuing.
Before starting, know that APIs depend on your code having some way to
make HTTP requests to remote servers. Most programming languages
offer a way to do this - usually (but not always) through a
cURL-based
library. For example, PHP has the
Client URL library
to build and issue a request. A mechanism like this will be necessary for making
API calls within your code.
For this tutorial, we will step through a shell script that uses native
cURL calls to generate an API request. You can view this script
here.
Feel free to download and run this script on any Linux
or Unix system with cURL (Note - this script will not work on Windows).
The first part of the shell script you'll want to examine is the
authentication mechanism. Using the user-provided client key and client
secret, it issues a new access token in the "/public/api/v1/token/generate"
cURL call. This token (which has a lifespan of 4 hours) is
used later on to authenticate API requests. This is a very
simplified version of how to authenticate API calls. In the near
future, we will provide details on best-practice API authentication.
Important! All API calls should be
made through HTTPS to ensure all sensitive
information (including your client key and secret) is
encrypted. You'll note this is done in all our code examples.
When the response is returned, the script parses out the access token for
later use. To keep things simple for this example, we've done a
quick regular expression. In a production-ready script, you'll want
to use a third-party JSON parser that can be used to read the response.
Like in the "Getting Started" example, this script uses the "/forms" api
resource. In this case, the script sets the Accept header to "application/json" to
specify we want a JSON response returned. Our APIs also support
returning data in XML. If you want, try replacing "application/json" with "application/xml"
in this script's cURL call.
Next, you'll see one query string parameter attached to this "/forms"
URL. If you consult our API documentation for the "/forms" GET
request, you'll see that it can take in a variety of optional parameters,
one of which is 'limit'. In this example, we've constructed
the API request to return a limit of 2.
Feel free to modify this script to include other query parameter filters
that are documented here.
Important! Trying to filter/search on a string?
You'll have to pass it through a url encoding function, which
cURL provides with its --data-urlencode parameter.
Finally, at the end of the cURL call, you'll see the script has an
Authorization header with "Bearer " and a placeholder for the access token.
This is always required to get a successful response.
Without it, the system will consider your request to be unauthorized
and will not return any data.
Once the script gets a response back from your site, it simply "echo"s it for you to look at.
In a real-life scenario, you could extend this script to consume the response and do something
with the information returned.
If you haven't already done so, try running this script on your
command-line. To do so, make sure you've installed cURL onto your
Linux/Unix (sudo apt-get install curl) or Mac machine. After
cURL is installed, follow the directions in the
script.
You now have the basic knowledge to code an API request to the One45 system.
Have an appetite for more? Check out our
Javascript
implementation of this example.
Tutorial #3 - How to create a Form Data report via APIs
Scenario
Let’s say you want to extract the same data that the Form Data Report gives you but across many groups at once. How would you get this data via One45 APIs?
Prerequisites
If this is your first time using the One45 APIs, it is strongly recommended to complete the two basic tutorials above (Tutorial #1 - Getting Started and Tutorial #2 - Programming an API request) and read the security overview before proceeding with the following instructions.
cURL
In this tutorial, we will be using cURL calls to extract data from One45 APIs. Even though this tutorial uses cURL, the system you eventually build or use to access APIs may be using different code or tools. cURL is being used for demonstration purposes.
A prerequisite to completing this tutorial is that you have a basic understanding of cURL and that you have cURL installed.
You can view full, executable examples of using our APIs with both cURL and JavaScript here: One45 API request snippets
One45 API Application
If you do not yet have an API Application created for you (or a client key and client secret to use in the next step), please follow the steps in the “Getting Started” tutorial to get your client key and client secret before beginning this tutorial.
Your One45 URL
Your One45 URL will look something like https://<your One45 site>.one45.com, or sometimes appended with /web/one45.php like https://<your One45 site>.one45.com/web/one45.php. You can find your One45 URL by logging in and then copying the URL in your browser address bar.
Start the tutorial
Generate an access token
Once you have your client key and secret, make the following API call:
curl -d 'client_key=<CLIENT KEY>' -d 'client_secret=<CLIENT SECRET>' <your One45 URL>/public/api/v1/token/generate
Which will return an access token in the following format:
The access token expires after 4 hours. We will be using an authorization header to pass the access_token to all subsequent API calls.
Fetch the Group IDs
First, we need the IDs of the groups we wish to extract the form data for. You can fetch the information for all groups using the following API call:
curl <your One45 URL>/api/v1/groups -H "Authorization: Bearer <token>"
Which will return an array of groups in the following format:
The actual responses you will receive from our APIs will be escaped JSON strings, so you might need to parse them into a JSON object.
You could then programmatically filter this list by role type, name matches, or any other criteria, then extract the group ids needed for the next steps.
Example: Fetching groups by name
If you wanted to find Group ID by exact group name instead (such as “Undergrad”), you could do it like so:
curl "<your One45 URL>/api/v1/groups?name=Undergrad" -H "Authorization: Bearer <token>"
Or if you’re trying to fetch a collection of groups that all have a similar name, you can use % symbols to fetch all groups that have a specific string in the name like so:
curl "<your One45 URL>/api/v1/groups?name=%Yr4%" -H "Authorization: Bearer <token>"
Which returns an array of groups with names that contain ‘Yr4’:
Example: Filtering for PGME groups
If you only want to report on PGME groups, you can filter the returned array of groups by role = 2 (resident).
Save the returned group ID(s) somewhere in your application. As these group IDs are unlikely to change, we recommend caching them to avoid unnecessary API calls.
Fetching the Form IDs
Now, we need the IDs of the forms we want evaluation data for. If you want to retrieve data for all forms, you can skip this step.
Example: Fetching all forms
You can call the API without parameters to get all forms.
curl <your One45 URL>/api/v1/forms -H "Authorization: Bearer <token>"
Example: Fetching forms by name
If we want to fetch forms by their name, we will have to query the forms API once per form using the form name as a GET parameter.
In this request, we’re url-encoding the data using the -G flag and the --url-encode option since the form name has spaces in it.
curl -G <your One45 URL>/api/v1/forms --data-urlencode "name=Evaluation of Course" -H "Authorization: Bearer <token>"
Which will return an array of forms (full response not shown):
If you’re trying to fetch a collection of forms that all have a similar name, you can use % symbols to fetch all forms that have a specific string in the name.
curl "<your One45 URL>/api/v1/forms?name=%ITER%" -H "Authorization: Bearer <token>"
This will return all forms that contain the word ‘ITER’ in the name.
Example: Fetching forms by group
If you’d like to fetch all forms that are shared with a particular group, use the ‘shared_with_group’ parameter.
curl "<your One45 URL>/api/v1/forms?shared_with_group=<group id>" -H "Authorization: Bearer <token>"
Fetch the Evaluation Data
Now we can start fetching the evaluation data.
Here is an example of calling the GET /evaluations API to fetch all evaluations from the form with ID 2492 that came from the group with ID 142.
curl "<your One45 URL>/api/v1/evaluations?form_ids[]=2492&group_ids[]=142" -H "Authorization: Bearer <token>"
Here is an example of how to filter using more than one form_id and more than one group_id:
curl "<your One45 URL>/api/v1/evaluations?form_ids[]=2492&form_ids[]=6783&group_ids[]=142&group_ids[]=143" -H "Authorization: Bearer <token>"
An array of evaluation objects will be returned (full response not shown):
Each evaluation object has the information you need to generate a row from the form data report (or the information to call additional APIs for pieces of data, depending on what fields you are after).
For example, if you normally generate a Form Data Report with the following fields, you can find that data in the APIs as listed:
Assemble & Hydrate Evaluation Data
Once all the data from these API requests has been captured, you will need to join the resulting data together (for example, you can traverse an evaluation, its form, questions, and answers to those questions) to build a report. This can be done using custom code or BI tools.
Tips & Additional Resources
Note: If you make too many API calls too quickly, your API application may be temporarily throttled (data will stop being returned) to prevent your One45 site from being crippled by too much traffic. See "Tutorial 4: Bulk data extraction" for tips and recommendations.
If you are using GET API calls only, you do NOT need a UAT site. GET calls can be used safely on your existing production site. This tutorial can be used without a UAT site.
If you are using POST, PATCH, or DELETE API calls, we strongly recommend using a UAT site to perform test runs of your system and ensure there are no bugs before connecting to your production site. POST, PATCH, and DELETE API calls will modify your data and cannot be undone.
How do I obtain a UAT site?
Contact your One45 CEM for additional information or to purchase a UAT site.
Tutorial #4 - Bulk data extraction
Access Token Expiration
Access tokens expire after 4 hours. If your application takes a long time to run, it’s possible that a token you generated at the beginning of its run may expire part way through. You can detect an expired token by monitoring for the 401 Unauthorized HTTP response. Alternatively, you could configure your application to proactively generate a new token every 4 hours.
Limit & Offset
Responses are paginated and multiple requests may need to be made using the “limit” and “offset” query string parameters in order to access all records that match your request. By default, all requests have a limit of 500 records. Here is an example of using offset and limit in an API request:
Your One45 URL will look something like https://<your One45 site>.one45.com or https://<your One45 site>.one45.com/web/one45.php. You can find your One45 URL by logging in and then copying the URL in your browser address bar.
The amount of data you fetch at a time is ultimately up to you. You may want to do it in smaller batches if fast response times are important to your application e.g. if the data will be displayed to a user on a web page. For generating a report, it might be preferable to fetch the data in larger batches if time isn’t as much of a concern. You may have to tweak this until you have a happy medium between response times and the amount of data returned.
Throttling
Throttling, also known as rate limiting, is the process of restricting the number of requests a user can make in a certain period.
When a throttling threshold is exceeded, the API limits any further requests for a period of time. Throttling behavior depends on the type and number of requests.
Note: Throttling is triggered by server load, not by a threshold of number or frequency of calls. This means at certain times of day API systems may be at greater risk of throttling (such as during the day when server load is higher from other activity). For this reason, we recommend that systems using APIs are run at night (or low activity times). Additionally, we recommend that external systems have the ability to detect, report, and retry (with reduced frequency or reduced limits) in the event of throttling.
How to detect throttling
When you implement error handling, use the HTTP error code 502 Bad Gateway to detect throttling.
How to avoid throttling
Reduce unneeded requests
Optimize your code to eliminate any unnecessary API calls
Cache frequently used data, such as group IDs and form IDs
How to avoid throttling
Reduce amount of data fetched with each request
There is a default limit of 500 results returned per API request. If you are experiencing throttling, you can choose to decrease this on every call using the ‘limit’ parameter to try and find a working threshold.
