Overview

An API can be thought of as a single system, but also as a collection of "resources". These resources are represented as individual items or unique functions that perform a specific task for you (in this case, retrieving a certain type of information). A resource is really the combination of two things: a URL (often referred to as an "endpoint") that defines the resource and an action that specifies what specific task you wish to invoke. In a REST-based API, these actions will accept one to four different values (called "methods") including: "GET" (for retrieving data), "PUT" (for inserting data), "POST" (for updating data), and "DELETE" (for removing data).

Making a Request / Call

All of our endpoints only have one action so we do not make you list that action's name. For example, a typical API resource call might look like: https://{host}/{endpoint}/{action}. Because we do not currently need to differentiate our actions, our resource calls look like this: https://{host}/{endpoint}. Here is what your resource request URL would look like if you wanted to retrieve a list of the organizations in your system: https://youinstitution.collegiatelink.net/api/organizations

Including Parameters

Parameters are additional values that typically act like "filters" or "toggles" on the requests you make. Every CollegiateLink API resource has a pre-defined list of these filters/toggles that it accepts. The values you pass for these parameters will typically have the effect of filtering your results in some way so as to give you a more specific set of data than you would have gotten without including the additional parameter.

Parameters are serialized in your request like this: https://{host}/{endpoint}?parameter1=value1&parameter2=value2. The first parameter you pass will start with a question mark character and come directly after the endpoint name. Any subsequent parameters will be listed thereafter, separated from the first parameter and one another with the ampersand character.

Please note that because the process of authenticating already requires you to include parameters such as the time, your public key, and a digital signature or hash value--you will likely already have started the serialization of your resource request URL.

Receiving a Response

When you make a call to the CollegiateLink API, you will likely receive one or two responses (either in XML or JSON, depending on the format you selected). First and hopefully, you will receive back the data that you requested based on the endpoint you selected and optional parameters you passed. If you did not successfully authenticate your request however, you may receive back a blank screen (or error code 401 - Unauthorized).

Result Pagination

Though it usually possible to make a call to the API for a single record of information, or to make a call that filters many results down to just a single record--in most cases you will be receiving back hundreds if not in some cases thousands of records. In order to keep the API operating within acceptable performance limits and help you avoid from inadvertently consuming more of your own network bandwidth than you might intend, the API will automatically paginate the data you request. This means that information is returned in "pages" where you will have a defined number of pages that represent all of your records, which themselves will be distributed among the pages.

If you have successfully connected to the API and made a sample query or two against endpoints that return more than one record, you will have seen the following elements (example in XML) near the top of your response data:

       <PageNumber>1</PageNumber>

       <PageSize>100</PageSize>

       <TotalItems>437</TotalItems>

       <TotalPages>5</TotalPages>

These elements are what allow you to know just how many total pages your request resulted in, how many total items there are, how many items there are per page, and what page of data you've just received.

How to Call Successive Pages

The following two parameters are available for all calls to the API. You may include them in your request in any order you wish, along with other call-specific parameters.

Parameter Description Type
page

The specific page number in a paginated list of results

Including this parameter in your call will limit the response to a single page matching the page sequence order represented by the page number.

INT
pageSize

The number of items to include in the page of results

Including this parameter in your call will adjust the response to only include no more than the number of items that you specify on each page.

Note: The maximum number of items that can be included regardless of the amount you specify is 500.

INT

In the example from the previous section, the request resulted in 437 records which are being split into 5 pages of 100 items each (though the last page would only include 37 items). When you first receive the information above, it will be part of page "1", meaning that you have four more pages to request from the API if you wish the full set of 437 records. Your code will need to capture the <TotalPages> value so that you can construct an iterative loop statement that will create the number of necessary additional requests to the API for your data.

EXAMPLE:
If your first request was something like:  https://{host}/{endpoint}?time=__&apikey=__...

Then your second request would need to be: https://{host}/{endpoint}?time=__&apikey=__...&page=2

The third request would be: https://{host}/{endpoint}?time=__&apikey=__...&page=3

...and so forth.

Further Information

If you have a question or are still unsure about some aspect of the API, please check out the Frequently Asked Questions section.

Have more questions? Submit a request