Table of Contents


Overview

The Aeries API is the primary way to get data into and out of the Aeries NextGen platform. It's an HTTP-based public REST API that users and apps can use to programmatically query data, post updates, and perform a wide variety of other tasks.


The Aeries API is composed of resources and related-resources that have actions which can be performed against them. Typically, you use resources to get data about a specific object in a domain, such as a specific student in the student domain, but these can also be used to update the data against a student, or even perform actions such as setting a student’s attendance status for a day. Throughout our documentation, we may refer to a resource and its actions as an "endpoint". For example, "send a GET request to the Users endpoint of /api/v1/users/{userid}".


Documentation  ↑

The Aeries API endpoint documentation can be found in the application itself, and with the developers help, self-generated in a sense using a tool called Swagger UI. By navigating to [your-domain]/swagger from a running instance of your application, you can find the documentation output in this Swagger UI format.


HTTP  ↑

All data transfers conform to HTTP/1.1, and all endpoints require HTTPS. Because the Aeries API is HTTP-based, it works with any language that has an HTTP library, such as C# or cURL. This means you can use the Aeries API directly in your browser. For example, requesting this URL in your browser...


... is equivalent to performing this cURL request:


Concerning HTTP call examples, for brevity throughout this document, we will shorten cURL examples to only the URL, with a ... representing the missing header information.


Host URL  ↑

Almost all requests are passed to a tenant’s district-name.aeries.com/api host URL. There may be future exceptions which will be listed here.


Authorization Tokens  ↑

Authorization tokens are one of the security items that allow you or your app(s) to access the Aeries API. Almost all Aeries API endpoints require an authorization token, so each time you access an endpoint, your request may require one. They typically perform two functions:

  • After initial authentication through our identity provider, they allow you or your app to access the Aeries API without requiring other credentials, like a user name and password. 

  • They allow us to identify who is accessing the Aeries API and apply the proper authorizations.

You obtain an authorization token through the authentication process. For more information, please see the documentation on Authenticating to Aeries.


Tenant IDs  ↑

Tenant IDs allow us to route requests within the Aeries API appropriately. These are assigned to a client during the client’s onboarding process and will remain with the client for the duration of their contract. Tenant IDs work with the authentication tokens, and other authorizations to ensure that the right processes are run, and data is retrieved. Almost all Aeries API endpoints require a Tenant ID, so each time you access an endpoint, your request may require one. 


Resources  ↑

A resource is a representation of a domain within Aeries and the collection of objects that it maintains. A specific object is a represented by a unique id within the Aeries datasets. For example, there are many User objects in the Users resource, each with a unique ID referencing a user in Aeries. 


The following example represents a call to the Users resource to get a student object.


This request would return the following data by default, formatted using JSON:


Resource Metadata

You can get a list of all fields, including the field name, description, and data type, of a resource's managed objects, such as a User, Student, or Staff. Send a GET request to the metadata endpoint and include the resource name, and optional managed resource:


The resulting JSON response will include the metadata property that lists all the supported fields for the given resource object:

/me  ↑

The /me resource is a special endpoint that translates to the object ID of the user whose authorization token is currently being used to make the API calls. This resource also houses other related endpoints that are specific to the authorized user, and is an important resource required for the initial scoping of authorizations. If you were to call the /me endpoint with your authorization token and the tenant id, you could retrieve the user's information:


A related-resource is a resource that is managed by a parent resource. For example, the Codes resource would manage the CodeSets resource, as the two are related. The following example will return a list of CodeSet objects from the Codes resource.

Each Id returned represents a CodeSet object.


Filters & Complex Parameters

Parameters for endpoints come in many forms, some are straight forward and defined in the route of an endpoint for filtering, such as:


Other times more robust filtering needs to be accomplished, and will be defined in the query-string of an endpoint, like so:


And in the case of data modifications, parameters will be defined in the body of the request:


And while most parameter types are straightforward, such as bool, string and int, there are also list and object types that can be specified in a request. The need for these will vary depending on the endpoint you are making a request to (mostly POSTs), and many times will be optional.

  • A list type is specified in JSON syntax, for example: ["firstitem", "seconditem", "thirditem"]

  • An object type (seen in example) is also specified in JSON syntax, for example: {"firstkey": "firstvalue", "secondKey": 123}


HTTP Result After a Create or Update

For create and update endpoints, an ID of the object created or updated will be returned. Additionally, the Aeries API will populate the result with a location header. This location header will present the requester with a relative endpoint that they can use to look the data up. The ID of the object will be included in the location header as well. The following request:


...would return the result as so:


Errors

If an endpoint fails for any reason, the Aeries API will respond with a standard HTTP error response. 


Versions

The Aeries API will have multiple versions as future requirements dictate. You can specify the version in your calls by adding "v" and the version number to the start of the request path. For example, here's a call to version 2 of the students resource:\