Equator API App

The Equator API app provides programmatic access to the system data and functionality, allowing colleges to create custom integrations with eBECAS/EDMISS.

Configuration

Follow these steps to set up the app.

1. From the Utilities menu, go to Apps, then click on the View button on the Equator API app. If you do not see the app listed, contact your system administrator.

2. Click on the Configuration button on the Equator API details page.
   The settings available are:

   • URL: This is the base url for all endpoints.

   • College Code: This is the college code for your institution.

   • API Key: This is your API Key

   • API Secret: This is your API Secret

   • Base64 Encoded: This is the base64 encoded string for <ApiKey:ApiSecret>

3. Choose the API user that will perform the actions from the API.

4. Click on Update.

   

View API Usage

The Equator API App provides a clear overview of your API activity, showing usage from the past 24 hours as well as daily totals from the last 5 days. This allows you to quickly monitor and track recent API consumption.

1. From the Utilities menu, go to Apps, then click on the View button on the Equator API app. If you do not see the app listed, contact your system administrator.

2. Your API usage for today and the last 5 days will display in API Usage section.

   

API Requests, Responses and Limits

Pagination

API endpoints that return multiple records use pagination to control the response size. When using these endpoints, you must implement a loop to fetch all pages.

By default, PageSize (the number of records per page) is set to 100. You can override this value by including the PageSize parameter in your request, up to a maximum of 1,000. If you request more than the allowed limit, the API will return HTTP status code 400 “Bad Request”.

To request a specific page, use the PageCount parameter to indicate the page number you want to retrieve.

Each response includes the following pagination fields:

• PageSize (integer, required): Number of records returned per page.

• PageCount (integer, required): Total number of pages.

• RecordsCount (integer, required): Total number of records matching the request.
  Note: The field name may vary depending on the endpoint. Refer to the API documentation for details.

To retrieve all records, perform multiple requests, incrementing the page number until all pages are processed. Keep the PageSize consistent across requests to avoid missing or duplicating records.

The total number of pages can be calculated as follows:

ceil(RecordsCount / PageSize)

Limits

There are limits to the number of API calls that your application can make,

Daily Rate Limit

API usage is subject to daily rate limits, applied per customer. Each customer is allocated 10,000 API calls per 24-hour period as a baseline, plus an additional 1,000 calls per active user license under their subscription. These limits apply only to API calls made through your own applications and do not include usage from integrations provided directly by Equator IT. Separate limits may apply to those integrations.

If your application exceeds the allocated limit, we may throttle or temporarily suspend access until usage returns within acceptable levels. We will notify you if sustained high usage requires a review or adjustment of your rate limits. Please contact us if you require increased capacity.

Exceeding a Limit

• Exceeding a rate limit will result in an HTTP 429 (too many requests) response.

• Exceeding the Page Size limit will result in a HTTP 400 (bad request) response.

Sample Request

To authenticate your requests, you need to include in the headers the following:

• Authorisation token: This is the Base64 Encoded string which you can retrieve from the settings view.

• COLLEGECODE: The college code available on the settings view.

• USERNAME: This is the username of a user that will be used on POST and PATCH requests. It is only required for endpoints that use any of these 2 methods. Make sure, from the user profile, that this user has the setting ‘API Account Access’ enabled. Without this setting enable on the user, your requests will receive an authorisation error.

The request, will look like the following (make sure to replace the details with your own):

curl -X GET "<YOUR FULL URL ENDPOINT>" \
     -H "Authorization: Basic <YOUR AUTHORISATION TOKEN>" \
     -H "Accept: application/json"
     -H "COLLEGECODE: <YOUR COLLEGE CODE>" \
     -H "USERNAME: <YOUR USERNAME>"

All the API responses are in json format

API Documentation

The list of endpoints available with their parameters and response examples are available on the URL in the following location of Equator API Configuration.

Testing

Before diving into integrating with our API, it's crucial to ensure that everything works as expected. By testing the endpoints, you can debug issues, familiarize yourself with the API response structures, and ensure your application behaves correctly. Here are some steps and tips for effective testing:

• Use a sandbox environment: Always start your testing in a sandbox or development environment. This ensures that your tests won't impact live data or disrupt actual business processes.

• Use tools like Postman: Postman is a popular tool for API testing, allowing you to send requests to your API endpoints and inspect responses.

If you need a testing collection for Postman, please contact the Equator IT Support team.

• Document unexpected behaviour: While testing, if you come across any behaviour that seems inconsistent with our documentation or unexpected in any way, note it down. This will help when reaching out to our support team or when making adjustments to your integration.

Best Practices

When integrating and working with APIs, it's crucial to maintain security, efficiency, and reliability. Here are some best practices to ensure that your API usage remains safe and robust:

Secure Your Credentials

• Never hardcode credentials: Do not embedded the API keys or authentication details directly in your code. Doing so is not only a security vulnerability but it also violates the Terms of Use of our API.

• Use environment variables: Store sensitive information like API keys in environment variables or secure configuration files, keeping them separate from your codebase.

• Rotate API keys: Regularly change your API keys to minimize the risk in case they get compromised.

Limit Data Exposure

• Least privilege principle: Only request the data you need. Avoid using endpoints that return more data than necessary, as this can expose sensitive information and consume more bandwidth.

Respect Rate Limits

• Stay within boundaries: Always be aware of our API rate limits. Exceeding these limits can lead to your application being temporarily blocked.

• Implement backoff logic: If you approach or hit rate limits, implement logic to back off and retry after a delay, rather than hammering the API continuously.

Secure Data Transmission

• Use HTTPS: Always use HTTPS for transmitting data to ensure it's encrypted and secure from eavesdropping or man-in-the-middle attacks.

By adhering to these best practices, you can ensure a secure, efficient, and reliable experience for both your application and its users.