Ares API

Sara Juel

Updated July 24, 2024 18:50

Installation

Using the Ares API requires Ares version 5.0.

Certain Microsoft .NET components must also be installed on the Ares Server to use the Ares API. These components are provided by Microsoft and will need to be installed separately as they are not included in the default Ares installation:

Ares 5.0: The Ares API requires the Microsoft ASP.NET Core 8.0 Runtime Hosting Bundle (download from Microsoft's website). This installer is provided by Microsoft and must be run separately.

Note: The latest installer for the Ares Web API is installed along with the Ares 5.0 server installer. However, the .NET Core components are not part of the default Ares install and will still need to be installed separately.

Customization Key Configuration

When configuring the API, confirm that the following customization keys have correct values:

APIUploadTempPath - The location on the server where temporary documents can be stored.
AresCopyrightPhysicalDocPath - The location on the server where copyright documents are stored.
APIConfig Table - The Web API URL specified in the APIConfig table. The record in the APIConfig table is created automatically by the Ares Updater for new installs. https://servername/ares/webapi/ is the Web API URL used for standard Ares installations. This path may differ if your Web API is installed in a non-standard location. For example, if your Web API is installed in a 'nonshib' folder, your URL would be https://servername/nonshib/webapi/.

If you are unsure which path to use for your API URL, please contact Atlas Support at support@atlas-sys.com if Atlas-hosted or your local Ares server administrator if self-hosted.

The Ares Updater attempts to set reasonable values for these keys based on existing values; however, in some cases, this may not be possible resulting in an empty string value.

Swagger Documentation

The Ares API has developer-oriented documentation built-in. You can get to the API Swagger documentation at https://servername/ares/webapi/swagger/.

*Replace 'servername' with the IP address or DNS.

Client Uploads

To use the Ares API instead of FTP or FileShare for uploading and downloading files within the Ares Client, please see Uploading Electronic Files to the Web for configuration instructions.

OData Support

OData query options are available to help filter result data for Ares API endpoints that return a list of objects. OData is currently supported for the LoanPeriods, Semesters, Sites, and Users endpoints.

Filtering

The $filter option allows filtering results by applying a Boolean expression. The filter expressions include logical and arithmetic operators, and string functions.

When using these operators, strings should be single-quoted, while dates and numbers must not be quoted. Multiple conditions can be combined with 'and' or 'or' (see examples below).

Filter Operators

eq	Equal
ne	Not equal to
gt	Greater than
ge	Greater than or equal to
lt	Less than
le	Less than or equal to
and	Logical and
or	Logical or
startswith(property, substring)	The property starts with the substring value
endswith(property, substring)	The property ends with the substring value
substringof(property, substring)	The property contains the substring value

Information on additional available comparators and operators can be found in the Microsoft documentation.

Examples

Return semesters starting between January 1st, 2020 and January 1st, 2022:

GET /<API URL>/Semesters?$filter=startDate gt 2020-01-01 and endDate lt 2022-01-01

Return loan periods for a given site (replace ALL in the example with the site code):

GET /<API URL>/LoanPeriods?$filter=site eq 'ALL'

Return sites that are valid pickup locations:

GET /<API URL>/Sites?$filter=availableForPickup eq true

Return users with email addresses ending in "gmail.com":

GET /<API URL>/Users?$filter=endswith(eMailAddress, '@gmail.com')

Available Endpoints

The syntax for the Ares API is in the following format: https://{your-ares-api-url}/{endpoint}. Please replace '{your-ares-api-url}' with your Web API URL as described below and 'endpoint' with one of the following endpoints listed below. For example, https://atlas-sys.com/ares/webapi/loanperiods.

Ares Web API URL

For standard Ares installations, the default URL for the Ares Web API is https://servername/ares/webapi where servername is the IP address or DNS of your server. However, your path to the Web API may differ if using a non-standard installation path for the Ares API on your server.

If you are unsure which path to use for your API URL, please contact Atlas Support at support@atlas-sys.com if Atlas-hosted or your local Ares server administrator if self-hosted.

Failed API Call

If any of the criteria are not met, the API will generate an HTTP status code error message. There are several possible error codes (e.g., 400 Bad Request, 401 Unauthorized, 404 Not Found, etc.) For example, when performing a Get Users/{username} call, if a user doesn't exist in Ares and there is not a UserValidation record for the user, the API will fail to locate the user and generate a 404 error.

Courses

The Courses endpoints can be used for retrieving information on course records.

Retrieves enrolled users for a given course | Retrieves course information | Retrieves items for a given course | Updates course information | Creates new courses

Retrieves enrolled users for a given course

GET /Courses/{course id}/enrollment

API Call:

The endpoint will take a course ID and return a list of enrolled users for that course

Response:

If the request is successful, the enrolled users for the course will be returned in JSON list format with a 200 Success code and the following details:
- Username (string)
- EnrollmentType (string)
If the request is not successful, an error code will be returned specifying the problem

Example Response:

[
 {
  "username": "student",
  "enrollmentType": "User"
 },
 {
  "username": "gradstudent",
  "enrollmentType": "ProxyInstructor"
 },
 {
  "username": "instructor",
  "enrollmentType": "Instructor"
 },
 {
  "username": "instructor2",
  "enrollmentType": "Instructor"
 }
]

Retrieves course information

GET /Courses/{course id}

API Call:

The endpoint will take a course ID and return details for that course

Response:

If the item exists, a JSON object listing the properties of the item will be returned.

Example Response:

{
 "courseId": 2,
 "creationDate": "2021-12-22T08:51:52.82",
 "createdBy": "admin",
 "createdVia": 0,
 "name": "Intro to Math",
 "courseCode": "MAT101",
 "description": null,
 "url": null,
 "semesterName": "Spring 2022",
 "startDate": "2022-01-05T00:00:00",
 "stopDate": "2022-05-20T00:00:00",
 "department": "Mathematics",
 "instructorDisplayName": "Instructor, Jessica; Instructor, Sam",
 "courseNumber": null,
 "coursePassword": null,
 "maxCopyright": null,
 "defaultPickupSite": "DEFAULT",
 "courseEnrollment": 12,
 "externalCourseId": null,
 "registrarCourseId": null,
 "courseInfo1": null,
 "courseInfo2": null,
 "courseInfo3": null,
 "courseInfo4": null,
 "courseInfo5": null
}

Retrieves items for a given course

GET /Courses/{course id}/items

Used to retrieve a list of items associated with the specified course.

API Call:

The endpoint will take a course ID and return a list of items associated with that course

Available Query Parameters:

limitAvailableItems (boolean): Indicates if only available items should be returned using a true/false value

Response:

If the request is successful, the items for the course will be returned in JSON list format including the details in the example below

Example Response:

[
 {
  "itemId": 1,
  "listItemId": null,
  "reasonForCancellation": null,
  "proxy": false,
  "itemFormat": "Book",
  "loanPeriod": null,
  "pageCount": null,
  "sortOrder": 0,
  "percentageOfWork": null,
  "courseId": 2,
  "activeDate": "2022-01-05T00:00:00",
  "inactiveDate": "2022-05-20T00:00:00",
  "neededBy": null,
  "callNumber": "B123.456",
  "currentStatus": "Item Available at Reserve Desk",
  "currentStatusDate": "2022-01-06T11:48:40.003",
  "pickupLocation": "DEFAULT",
  "processingLocation": "DEFAULT",
  "itemType": "Monograph",
  "digitalItem": false,
  "documentType": "HardCopy",
  "location": null,
  "aresDocument": false,
  "instructorProvided": false,
  "copyrightRequired": false,
  "copyrightObtained": false,
  "natureOfWork": null,
  "pagesEntireWork": null,
  "visibleToStudents": true,
  "doi": null,
  "espNumber": null,
  "citedIn": null,
  "pages": null,
  "shelfLocation": null,
  "title": "Calculus: Early Transcendentals",
  "author": "Stewart, James",
  "publisher": "Cengage Learning",
  "pubPlace": null,
  "pubDate": null,
  "edition": "8",
  "isxn": "9781285741550",
  "articleTitle": null,
  "volume": null,
  "issue": null,
  "journalYear": "2015",
  "journalMonth": null,
  "editor": null,
  "referenceNumber": null,
  "itemBarcode": null,
  "itemInfo1": null,
  "itemInfo2": null,
  "itemInfo3": null,
  "itemInfo4": null,
  "itemInfo5": null
 }
]

Updates course information

PATCH /Courses/{course id}

Used to update information for a specific course record in Ares.

API Call:

In addition to the ID for the course specified in the API call, requests to this endpoint must contain a body in the JSON Patch format using the "replace" action to specify which Ares fields on the course record to overwrite with new values:

[
  { "op": "replace", "path": "/<aresField1>", "value": "<NewValue>" },
  { "op": "replace", "path": "/<aresField2>", "value": "<NewValue>" }
]

Note: The path property must specify an Ares course field name using camelcase, e.g. 'fieldName'

Example Call:

The following example will update the enrollment number for a course to 60 students and also clear out any values from its CourseInfo1 field:

[
    {"op": "replace", "path": "/courseEnrollment", "value": "60"},
    {"op": "replace", "path": "/courseInfo1", "value": null}
]

Additional Notes:

To remove a value from a field, use the replace action to set the new value for the field to null, for example:
```
{"op": "replace", "path": "/articleTitle", "value": null}
```
If the SemesterName field is changed but new StartDate and StopDate field values are not specified, the course's start and stop dates will automatically be set to the start and end dates for the specified semester.

Response:

The endpoint can return the following responses:

200 Success: The operation was completed successfully and a JSON model of the updated course is returned
400 Bad Request: The request information was invalid (see section below)
401 Unauthorized: The request was not properly authorized
404 Not Found: The specified course ID was not found

The 400 Bad Request code will be returned in the following circumstances:

The JSON Patch request body specifies a field that doesn't exist for the Ares course
A specified course field has an invalid value, for example:
- MaxCopyright or CourseEnrollment is set to less than zero
- SemesterName is set to a nonexistent semester
- DefaultPickupSite is set to a nonexistent site or to an existing site that is not available for pickup
- Attempting to set a value in a read-only field, such as:
  - CourseId
  - CreationDate
  - CreatedBy
  - CreatedVia
  - InstructorDisplayName

Creates new courses

POST /Courses

Used to create a new course record in Ares.

API Call:

The endpoint requires a JSON body containing information in the following format:

Example Call:

{
 "name": "string",
 "courseCode": "string",
 "description": "string",
 "url": "string",
 "semesterName": "string",
 "startDate": "2022-04-27T14:54:49.844Z",
 "stopDate": "2022-04-27T14:54:49.844Z",
 "department": "string",
 "instructor": "string",
 "courseNumber": "string",
 "coursePassword": "string",
 "maxCopyright": 0,
 "defaultPickupSite": "string",
 "courseEnrollment": 0,
 "externalCourseId": "string",
 "registrarCourseId": "string",
 "courseInfo1": "string",
 "courseInfo2": "string",
 "courseInfo3": "string",
 "courseInfo4": "string",
 "courseInfo5": "string"
}

Additional Behavior:

If a semesterName is specified but no startDate and stopDate, these fields will be set to match the specified semester's start and end dates
If startDate and stopDate are specified but no semesterName, Ares will search for the shortest semester that encompasses the given dates and match it to populate this field
If defaultPickupSite is not specified, it will be set to the value defined in the DefaultPickupSite customization key

Response:

If successful, the new course will be returned as a JSON object with a 201 Created code
If unsuccessful, the endpoint will return a 400 Bad Request or 401 Unauthorized code

The 400 Bad Request code will be returned in the following circumstances:

The JSON body that specifies the new course fields has any invalid fields
The new course has invalid values for any fields, for example:
- A non-existent semesterName
- A non-existent default pickup location, or a location that is not available for pickup
- A negative value for max copyright or course enrollment

Users

The Users endpoints can be used for retrieving information on user records.

This endpoint supports OData filtering.

Retrieves user details for a given username | Retrieves user details for a given external user ID | Retrieves courses associated with a given username

Retrieves user details for a given username

GET	/Users/{username}
If the user exists- User information will be returned. If the user does not exist- The API will search for a UserValidation record with the username. If the UserValidation record exists- The new user will automatically be created based on the UserValidation data and all associated courses will be updated with the new user information. This is accomplished by searching all CourseUserValidation records to locate any courses the user belongs to and then running course maintenance for any matches. Retrieves user details for a given external user ID
GET	/Users/ExternalUserId/{id}
API Call: If the user exists- User information will be returned. If the user does not exist- The new user will automatically be created based on the UserValidation data and all associated courses will be updated with the new user information. This is accomplished by searching all CourseUserValidation records to locate any courses the user belongs to and then running course maintenance for any matches. The ApiConfig table contains a new column, ExternalUserIdMapping, that includes a list of all of the registered API users (identified by their unique API key guide). When a user makes a call through the Ares API with a given key, Ares will retrieve the matching record from ApiConfig file. The ApiConfig will define what field to match by checking the ExternalUserIdMapping in the Config file. Response: If there are multiple users with the same value in the field mapped to the externalID, a type 300 (Multiple Choices) HTML Status Code will be returned. Retrieves courses associated with a given username
GET	/Users/{username}/courses — or — /Users/{username}/courses?activeCourses=true
API Call: If the user exists- All courses associated with that user will be returned. If the user exists and optional active courses parameter (?activeCourses=true) is used- If the optional parameter ActiveCourses is included and marked as true, only active courses will be returned. Start and stop dates are calculated based on the existing start and stop date override rules. For students, this will be based on the course’s start and stop date rules. For instructors, this will be based on the semester’s item addition date and the course’s stop date. Response: For each course, the result will display the user's role by stating if the user has instructor privileges for the course, followed by a course listing with any related information.

Loan Periods

The Loan Period endpoints can be used for retrieving information on loan periods.

This endpoint supports OData filtering.

Retrieves a list of configured loan periods | Retrieves loan period details

Retrieves a list of configured loan periods

GET	/loanperiods
Used to return a list of all configured loan periods. Retrieves loan period details
GET	/loanperiods/{loanperiodid}
Used to return details on a specific loan period designated in the API call.

Sites

The Site Code endpoints can be used for retrieving information on pickup and processing locations.

This endpoint supports OData filtering.

Retrieves a list of configured sites | Retrieves site details

Retrieves a list of configured sites

GET	/sites
Used to return a list of all configured sites. Retrieves site details
GET	/sites/{sitecode}
Used to return details on a specific site designated in the API call. Details include: Sitecode Description Available for Pickup (true/false) Available for Processing (true/false)

Items

The Item endpoints can be used for creating, uploading, and routing new items.

Creates new items

POST /Items

Used to create new item records in Ares.

API Call:

The endpoint requires a JSON body containing a value for at least the following item fields:
- CourseId
- ActiveDate*
- InactiveDate*
- ProcessingLocation*
The endpoint will validate the new item with the fields established in the JSON body.

*If a valid CourseID is supplied, the endpoint will use the course information to locate and pre-populate other required fields (i.e., ActiveDate, InactiveDate, and ProcessingLocation) if values are not specified for these fields in the API call. For example, ActiveDate and InactiveDate will be set to the semester start and end date for the course if values for these fields are not specified in the call.

Example Call:

{
   "courseId": 0,
   "currentStatus": "string",
   "currentStatusDate": "2022-04-27T19:56:50.673Z",
   "activeDate": "2022-04-27T19:56:50.673Z",
   "inactiveDate": "2022-04-27T19:56:50.673Z",
   "neededBy": "string",
   "callNumber": "string",
   "pickupLocation": "string",
   "processingLocation": "string",
   "itemType": "Monograph",
   "digitalItem": true,
   "documentType": "string",
   "loanPeriod": 0,
   "location": "string",
   "aresDocument": true,
   "instructorProvided": true,
   "copyrightRequired": true,
   "copyrightObtained": true,
   "natureOfWork": "string",
   "pagesEntireWork": 0,
   "visibleToStudents": true,
   "doi": "string",
   "espNumber": "string",
   "citedIn": "string",
   "pages": "string",
   "pageCount": "string",
   "shelfLocation": "string",
   "title": "string",
   "author": "string",
   "publisher": "string",
   "pubPlace": "string",
   "pubDate": "string",
   "edition": "string",
   "isxn": "string",
   "articleTitle": "string",
   "volume": "string",
   "issue": "string",
   "journalYear": "string",
   "journalMonth": "string",
   "editor": "string",
   "referenceNumber": "string",
   "itemBarcode": "string",
   "itemInfo1": "string",
   "itemInfo2": "string",
   "itemInfo3": "string",
   "itemInfo4": "string",
   "itemInfo5": "string"
}

Response:

The endpoint will take the value of the CourseID to locate and pre-populate other required fields (e.g., ActiveDate) from the course fields if values are not specified for these fields in the API call.
The endpoint will also apply general item validation to the new item, which includes validating the item's pickup and processing locations against the Sites table and validating the item's start and end date fields against the parent course's start and end dates.
On a successful post, the endpoint will return a JSON object that describes the newly created item with any applicable field values.

Retrieves item information

GET /Items/{item id}

Used to retrieve details for an item in Ares.

API Call:

The endpoint will take an item ID and return details for that item

Response:

If the item exists, a JSON object listing the properties of the item will be returned.

Example Response:

{
   "itemId": 76,
   "listItemId": null,
   "reasonForCancellation": null,
   "proxy": false,
   "itemFormat": "Book",
   "loanPeriod": null,
   "pageCount": 6,
   "sortOrder": 0,
   "percentageOfWork": null,
   "courseId": 15,
   "activeDate": "2022-01-01T00:00:00",
   "inactiveDate": "2023-01-01T00:00:00",
   "neededBy": null,
   "callNumber": null,
   "currentStatus": "Item Activation Pending",
   "currentStatusDate": "2022-04-21T13:53:44.327",
   "pickupLocation": "BETA",
   "processingLocation": "BETA",
   "itemType": "Monograph",
   "digitalItem": false,
   "documentType": "HardCopy",
   "location": null,
   "aresDocument": false,
   "instructorProvided": false,
   "copyrightRequired": false,
   "copyrightObtained": false,
   "natureOfWork": null,
   "pagesEntireWork": null,
   "visibleToStudents": true,
   "doi": null,
   "espNumber": null,
   "citedIn": null,
   "pages": "5-10",
   "shelfLocation": null,
   "title": "The Solar System",
   "author": "Dana Backman",
   "publisher": null,
   "pubPlace": null,
   "pubDate": null,
   "edition": null,
   "isxn": "1439050368",
   "articleTitle": null,
   "volume": null,
   "issue": null,
   "journalYear": "2020",
   "journalMonth": null,
   "editor": null,
   "referenceNumber": null,
   "itemBarcode": null,
   "itemInfo1": null,
   "itemInfo2": null,
   "itemInfo3": null,
   "itemInfo4": null,
   "itemInfo5": null
}

Route items

POST /Items/{id}/Route

Used to route items to new statuses.

API Call:

The endpoint accepts the following JSON body containing a single string object named "newStatus" to define where the item should be routed. Replace "New Item Status" with the appropriate status. See example JSON POST body below:

{
 "newStatus": "New Item Status"
 }

Response:

The API will route the item to the new status following any applicable routing rules set in Ares. After all of these actions have completed, the endpoint will return a JSON response with the item's "CurrentStatus".

Downloads item files

GET	/items/{item id}/downloadfile?FileType={Item or PermissionsDocument}
Used to download files. API Call: The endpoint accepts a JSON body containing a value for the following item field: FileType- A single parameter value of Item or PermissionsDocument. Response: Downloads the file of the specified type associated with the provided item ID.

Deletes items

DELETE	/items/{item id}/delete
Used to delete files. API Call: The endpoint accepts a JSON body containing a value for the following item field: FileType- A single parameter value of Item or PermissionsDocument. Response: Deletes the file of the specified type associated with the provided item ID. Small file uploads Files smaller than 150MB
POST	/Items/{item id}/upload
Used for uploading files. This endpoint supports the upload of one (1) file attachment up to 150MB. Files and their associated items will be uploaded utilizing the same process as the Client: The file will be renamed and saved to the location defined in the PhysicalDocPath Customization Key. The request will be updated with the file's name and document type. The request will be routed to the appropriate status. The Internet Information Services (IIS) limits file uploads to 30MB by default - to permit uploads larger than this limit, your IT department will need to change the IIS configuration or use the large file upload request below. Large file uploads Files larger than 150MB Files too large to upload in a single POST request can be uploaded in multiple parts using an upload session. This involves three endpoints: Create Upload Session, Append, and Commit. The max file permitted for uploads, in MB, is controlled by the value of the MaxUploadSize Customization Key. Default value: 150MB.

Creates session ID

POST

/items/{item id}/sessionupload

Used to create an upload session. The first upload session will create a file and each subsequent upload will need to be done using the append endpoint to add additional data to the file. Part 1 of 3 calls required to upload large files.

API Call:

The endpoint requires a JSON body containing a value for the following item fields:
- Filename
- Filesize (in bytes)
- FileUploadType- A single parameter value of Item or PermissionsDocument
The file is encoded as a byte array with a SHA256 hash upon upload.

Response:

The response may include one or more of the following:

Upload Session ID (GUID): The ID of the created upload session, which must be used in future requests for this file.
FileAlreadyExists (Boolean): If True, this file already exists on the server. It should not be uploaded; instead, send a Commit message (see below).
MaxAppendSize (in bytes): The maximum permitted size of an append request to this endpoint.

Append to an upload session

PUT

/items/{upload session id}/append

Used to append. Part 2 of 3 calls required to upload large files.

API Call:

The endpoint requires a JSON body containing the following:
- A byte array, up to the MaxAppendSize received in the Create Upload Session response message. If the total file is larger than MaxAppendSize, break the file up into multiple messages. Bytes do not need to be encoded.

Response:

FileAlreadyExists (Boolean): If True, the file already exists on the server. It should not be uploaded; instead, send a Commit message (see endpoint below).

Commits each part of the file to the session ID

POST	/items/{upload session id}/commit
Used to commit the appended data to the upload session. Part 3 of 3 calls required to upload large files. Response: Once the entire file has been uploaded a commit message will confirm completion of the file upload (if a file was uploaded) and will associate the new or existing file with the item ID created in the original Create Upload Session response message.

Updates items

PATCH /Items/{item id}

Used to update information for a specific item record in Ares.

API Call:

In addition to the ID for the item specified in the API call, requests to this endpoint must contain a body in the JSON Patch format using the "replace" action to specify which Ares fields on the item record to overwrite with new values:

[
  { "op": "replace", "path": "/<aresField1>", "value": "<NewValue>" },
  { "op": "replace", "path": "/<aresField2>", "value": "<NewValue>" }
]

Note: The path property must specify an Ares course field name using camelcase, e.g. 'fieldName'

Example Call:

The following example will update an item's DOI field to 123, the ESPNumber field to 456, the ArticleTitle field to null, and the ItemInfo5 field to ItemInfo:

[
    {"op": "replace", "path": "/doi", "value": "123"},
    {"op": "replace", "path": "/espNumber", "value": "456"},
    {"op": "replace", "path": "/articleTitle", "value": null},
    {"op": "replace", "path": "/itemInfo5", "value": "ItemInfo"}
]

Additional Notes:

To remove a value from a field, use the replace action to set the new value for the field to null, for example:
```
{"op": "replace", "path": "/articleTitle", "value": null}
```
Any Ares item field available in the create item endpoint is available for use with this endpoint, except for the CourseID, CurrentStatus and CurrentStatusDate fields. The CurrentStatus and CurrentStatusDate fields can only be updated for an item using the route items endpoint. CourseID is read-only and cannot be modified for an item once it is initially set.

Response:

The endpoint can return the following responses:

200 Success: The operation was completed successfully and the updated item record will be returned in the same JSON object format as the retrieve item information endpoint response with a 200 Success code.
400 Bad Request: The request information was invalid, for example, it specified a non-existent Ares field or attempted to set an Ares field to an invalid value

Note: The 400 Bad Request code will also be returned when attempting to set the value in an Ares field that is not supported for use with this endpoint (e.g., CourseID). See the Additional Notes callout above for more information on supported fields.
401 Unauthorized: The request was not properly authorized
404 Not Found: The specified item ID was not found

Retrieves item notes

GET

/items/{item id}/notes

Used to retrieve a list of notes for a specified item record.

API Call:

The endpoint will take an item ID and return a list of notes for the specified item

Response:

If the request is successful, the notes for the item will be returned in JSON list format with a 200 Success code and the following details for each note:
- ItemID (integer)
- AddedBy (string)
- NoteDate (DateTime)
- NoteType (string)
- Note (string)
- NoteID (integer)
If the request is not successful, one of the following errors will be returned:
- 400 Bad Request: Indicates that the request was missing required information
- 401 Unauthorized: Indicates that the request was not properly authenticated
- 404 Not Found: Indicated that an item associated with the specified item ID was not found
If the specified item does not have any associated notes, the endpoint will return an empty list

Shared Lists

The Shared Lists endpoints can be used for retrieving information and deleting course items in shared lists. These endpoints work similarly to the endpoints for Items, except they don't accept a FileType parameter because shared list items have only one file type (e.g., no permissions documents).

Retrieves shared list items | Downloads items from shared lists | Deletes items from shared lists

Retrieves shared list items

GET	/sharedlistitems/{item id}
Used to return shared list item records, in JSON format. Downloads items from shared lists
GET	/sharedlistitemsitems/{item id}/downloadfile
Used to download the item file associated with this shared list item. Deletes items from shared lists
DELETE	/sharedlistitems/{item id}/deletefile
Used to delete the item file that is associated with the shared list item.

Semesters

The Semesters endpoint can be used for retrieving information about semesters defined in Ares.

This endpoint supports OData filtering.

Retrieves semesters

Retrieves semesters

GET	/semesters
Used to return semester records in JSON format with the following properties: SemesterName (string) StartDate (datetime) EndDate (datetime) ItemAdditionDate (datetime): The date when instructors can begin adding items for courses assigned to the semester

Token

Retrieve authentication token

Retrieve authentication token

Post	/api/Token
Retrieves an authentication token for the provided staff credentials.

Authentication

Most of the actions will require authentication. There are 2 ways to authenticate in the Ares API: Ares API Key or staff tokens.

API Key

You can create an API key in the Ares Customization Manager's APIConfig table, if necessary. A default record in the APIConfig table is created automatically by the Ares Updater for new installs (see Installation section above).

Testing the Authentication

To test in the swagger interface, you can click on Authorize in the top right corner of the swagger interface. A pop-up like an image shown below will appear.

The first option (Name: X-ARES-API-KEY) is for the API Key; Just paste the API key directly into the value and click authorize and you should be good.
For the staff token authentication, note that it currently has a 5-minute timeout. You would need to POST to the Token operation to get a JWTvalue. In the swagger interface, you would enter BEARER <JWT value from Token response>

Additional Information

If there is specific functionality that you are looking to use to integrate with your services, we encourage you to submit enhancements & ideas to UserVoice at https://uservoice.atlas-sys.com/. Thanks!

Installation

Customization Key Configuration

Swagger Documentation

Client Uploads

OData Support

Filtering

Filter Operators

Examples

Available Endpoints

Ares Web API URL

Failed API Call

Courses

Retrieves enrolled users for a given course

Retrieves course information

Retrieves items for a given course

Updates course information

Creates new courses

Users

Retrieves user details for a given username

Retrieves user details for a given external user ID

Retrieves courses associated with a given username

Loan Periods

Retrieves a list of configured loan periods

Retrieves loan period details

Sites

Retrieves a list of configured sites

Retrieves site details

Items

Creates new items

Retrieves item information

Route items

Downloads item files

Deletes items

Small file uploads **Files smaller than 150MB**

Large file uploads **Files larger than 150MB**

Creates session ID

Append to an upload session

Commits each part of the file to the session ID

Updates items

Retrieves item notes

Shared Lists

Retrieves shared list items

Downloads items from shared lists

Deletes items from shared lists

Semesters

Retrieves semesters

Token

Retrieve authentication token

Authentication

API Key

Testing the Authentication

Additional Information

Articles in this section

Small file uploads Files smaller than 150MB

Large file uploads Files larger than 150MB