Equator API

Our API is designed to enable users to build robust integrations that help them customise and get the most value out of our products.

Our API is built using REST convention and it uses Basic Access Authentication.

The Equator API is a paid add-on which is included in some of our subscription plans. Check with your system administrator if this add-on is available on your subscription.

Setting Up

Basic authentication requires to include on the headers of each request a set of credentials. These credentials are generated in the app.

Retrieve and Update your API Access Credentials

1. From the main navigation, go to Utilities > Setup Configuration. The Configuration window will display.

2. From the sidebar menu, on the Configuration Window, go to Setup>API Portal Access.

3. From the API Portal Access section, you can view and update the API credentials.

4. To create/update the API credentials, click on New and then on Save.

The settings available are:

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

• API Url: This is the base url for all endpoints.

• 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>

In the next section, you will see a sample request and how to use these settings to authenticate your requests to the API.

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 eBECAS/EDMISS: Main > Utilities > Setup Configuration > Setup > API Portal Access.

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.

• 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.

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.