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

From the main navigation, go to Utilities > Setup Configuration. The Configuration window will display.
From the sidebar menu, on the Configuration Window, go to Setup>API Portal Access.
From the API Portal Access section, you can view and update the API credentials.
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 ‘eBECAS Portal 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):

CODE

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:

https://ebecas.equatorit.net/ebecas.portal/

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.