This article is intended for Aeries administrators. There is a separate document intended for vendors that details every API End Point in the system, the parameters, and the output.
Aeries SIS contains an integrated API system. An "API" is an Application Programming Interface. It allows outside systems (like 3rd Party Vendors) to call functions inside of Aeries to perform actions like getting data out or changing information.
Aeries administrators can access the API Security page in the Security node of the navigation menu. This page allows the customer to create 3rd party product records and manage the permissions that each product is granted.
3rd Party Product
On the API Security page, the Aeries administrator can Add, Change and Delete records for 3rd party products. When adding a new product, only the Product Name is required. A Comment can be added to store additional information if needed. Also, if the vendor will access the Aeries OneRoster API, check the box for OneRoster. Click the Insert button to save the record.
After saving the record, check the box to Display Certificate Details. Make note of the Certificate value that displays. If the vendor will use the OneRoster API, also check the box to Display Consumer ID & Secret Keys for OneRoster. Make note of the Consumer ID and Consumer Secret Key values that display.
You will need to provide the 3rd party vendor with the following pieces of information:
Aeries URL: This is the base URL for your Aeries Web application. The website needs to be publicly accessible from outside your local network, and it is HIGHLY recommended that it be secured with an SSL certificate (HTTPS). Simply browse to your Aeries login page, then copy everything before the last slash (“/”) in the browser’s address bar. In the example below, the Aeries URL is https://aeries.mydistrict.org.
Note: If your Admin and Teacher Portals are not available externally or if they use Integrated Windows Authentication, then it is best to provide the URL of your Student Portal instead. The API works the same regardless of the portal type.
API Certificate (for regular Aeries API): Using this unique string provides security for the Aeries API against unauthorized access. A sample Certificate is highlighted below for illustrative purposes only. Each Certificate will be different.
Note: Vendors may use different names for the API Certificate, but they are all referring to the same thing. Examples include “API Key”, “App Key”, etc. Although some vendors may refer to this information as “provided by Aeries”, there is no need to contact Aeries Support to obtain API-related information to give a vendor; all of the required information is available on the API Security page in Aeries.
Consumer ID (for OneRoster API): This is one piece of information that the vendor will require for OAuth 2.0 authentication, as described in the OneRoster API Authentication article. A sample Consumer ID is highlighted below for illustrative purposes only. Each Consumer ID will be different.
Consumer Secret Key (for OneRoster API): This is one piece of information that the vendor will require for OAuth 2.0 authentication, as described in the OneRoster API Authentication article. A sample Consumer Secret Key is highlighted below for illustrative purposes only. Each Consumer Secret Key will be different.
IMPORTANT: Do not share a Certificate, Consumer ID, or Consumer Secret Key with anyone other than the vendor for which it was created. Always create a separate 3rd party product record for each vendor/product that will access the API. These credentials cannot be changed once they are created. If credentials are compromised, the 3rd party product record must be deleted and a new one created.
After creating a 3rd party product record, the Aeries administrator can grant appropriate permissions to various tables and program areas within Aeries. The 3rd party vendor should be prepared to provide information on which permissions are required for their product to access the API. If it is unclear what permissions are needed, we recommend using your best judgment to determine the minimum permissions required for the 3rd party product to interface with Aeries based on the functionality of that particular product. The image below illustrates some of the current tables and program areas that are available. As the API is enhanced, there will be more areas from which to choose.
For the permissions required for the OneRoster API, refer to the OneRoster API setup article.
There are two types of API permissions: Read and Update. Read permissions only allow Aeries data to be retrieved via the API but not modified. Update permissions allow Aeries data to be modified via the API. Not all areas of the API currently support Update permissions, but more will be added as the API continues to be enhanced.
To grant a permission, click the box next to the appropriate table/program area under the Read or Update column, and the box will become checked with a green background. To remove a permission, click the box again, and the check mark and green background will go away. There is no “Save” button for API permissions. Changes are saved immediately as you click the various boxes.
Default Database and Multi-Year Access
The Aeries API utilizes the AeriesNetConnections.config file to determine the database to which it should connect. The API can only be used to connect to the Default Database Group defined in this file. The API can be used to connect to a previous year database within the default Database Group if a parameter named DatabaseYear is included in the query string of the API request. If the DatabaseYear parameter is omitted or invalid, then the API will connect to the Default Year within the default Database Group. The DatabaseYear parameter should be in the format of “YYYY”, using the year at the start of the school year (e.g., “2017” for the 2017-2018 school year).
Aeries Software Elite Partners
Our Elite Partners are companies that have formal business relationships with Aeries Software that can involve co-marketing and sales campaigns as well as financial relationships. Our Elite Partners automatically have 3rd party product records on the API Security page. The Elite Partner status is indicated by a red message above the product name.
These records cannot be deleted. Some Elite Partners may have Certificates that are not visible to the customer, while others may be visible. If the Certificate is not visible, then it is only necessary to grant the permissions in order for that Elite Partner to access the API. If the Certificate is visible, then it must be provided to the Elite Partner. The situation may vary depending on the Elite Partner.
Note: If no permissions are granted, then the Elite Partner will not be able to access your Aeries data via the API. Aeries Software and our Elite Partners respect the security and privacy of our customers’ data.