What is the API

Introduction

The Ans Application Programming Interface (API) allows you to automate processes within your application landscape which involve Ans. You can think of processes like provisioning users, assignments and question banks where Ans is the application which receives data from another application. Some data is generated in Ans, for example results of assignments. This data can be extracted from Ans using the API. In addition to the API, you can also use webhooks. Webhooks support realtime data exchange of data which is generated in Ans. The entire API documentation can be found here.

Prerequisites

Before you begin, you should have a basic understanding of a REST API and HTTP actions, such as: GET, CREATE, UPDATE, DELETE. If you are going to use Ans to setup large-scale integrations for your whole school, you should definitely have knowledge about your own application landscape and the architecture of Ans as well. Without this knowledge it is hard to understand the concept of data exchange via APIs.

You should set clear goals what you want to achieve with integrations. For example, which processes do you want to support with automation? Start with a functional design which is translated in a technical design with data mapping. After that, start developing your integrations. Depending on your license you have, you can make use of the stage environment to test your integrations before deploying them on the production environment.

Identifiers

Ans makes use of identifiers for every object that is accessible through the API V2. These identifiers are unique per type of object, meaning that no two assignments will have the same identifier, however an assignment and an exercise might, for example. Ans identifiers are created sequentially, so newer objects have a higher identifier than older objects of the same type. 

Ans identifiers can be used in API V2 requests to indicate the exact object that the request is for. The Ans identifiers can also be used in request bodies as foreign keys. 

Some objects, such as assignments, classes, courses, exercises, groups and question banks have an external_id field. This field can be used to fill in the identifier of any external source and will not be used by Ans. The purpose of this is to be able to identify the origin of the object within the external source. The field can also be searched on, therefore it is possible to search for the object when only the identifier of the external source is available.

Authorisation

The first step is to setup the authentication for your integrations. Ans is using the Bearer token method to support authentication. To create a token, follow the steps below.

The provided token is a Bearer token and needs to be set in the Request Header with key Authorization and value "Bearer [token]" for every request. The API V2 also supports authentication via OAuth2, however this is only used for integrations. The provided token can only be used with the Ans V2 API.

error_outline The generated token is only shown once. If the generated token is lost, you will need to generate a new one.

In all request, an id attribute must be given to execute the request. For example, to get the results of a certain assignment, the assignment_id attribute must be given in the URL of the request. For some attributes, you will need the school_id attribute. This can be found on the API token page in the user settings.

Pagination

The API generates several headers due to its use of pagination, this includes:

- Link, the standard link header defined in RFC 8288
- Current-Page, which shows the current page of the requested data
- Page-Items, which shows the amount of items per page
- Total-Pages, which shows the total amount of pages available
- Total-Count, which shows the total count of objects that was requested

By default every list request returns 20 records. It is possible to adjust the number of records per page with the usage of the "limit" parameter. You can specify any value between 1 and 100 (records per page). For example:

GET https://ans.app/api/v2/background_jobs?page=2&limit=10

Rate Limits

The API enforces a rate limit of 500 requests per minute per school. The limit applies to the entire school, regardless of the number of devices or IP addresses in use. Meaning, if multiple devices at the school are making a high volume of API requests, they will share a single overall limit. If the combined requests exceed this limit, further requests will be restricted, even if an individual device has not reached its own limit. Please ensure your school's API usage stays within the limits set in your pricing plan.

If the rate limit is exceeded, the API responds with a "HTTP 429 Too Many Requests" response code. You can use the response headers below to confirm the current rate limit and monitor the number of requests remaining in the current minute.

- RateLimit-Limit, the current limit for your account
- RateLimit-Remaining, the number of remaining requests in the current minute
- RateLimit-Reset, the number of seconds until the limit is reset

Increasing the API rate limit is available as an add-on, as it is based on usage. If you want to increase the rate limit for your school, please contact your Customer Success Manager for more information on the options.

In the following articles we’ll explain how to use the Ans API to create, update and delete users, question banks and assignments.