1. Atlas Systems
  2. Ares
  3. General

Ares API

Print Friendly and PDF Follow

Avatar
Sara Juel
Updated

Installation | Swagger Documentation | Client Uploads | OData Support | Available Endpoints | Authentication | Additional Information

Installation

Using the Ares API requires Ares version 5.0. The Ares API requires the DotNetCore components. This installer is provided by Microsoft. The latest installer for the Ares Web API is installed along with the Ares 5.0 server installer.

When configuring the API, confirm that the following CustKeys 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

Failed API Call | Courses | Users | Loan Periods | Sites | Items | Shared Lists | Semesters

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 | Retrieves item information | Route items | Downloads item files | Deletes items | Small file uploads | Large file uploads | Creates session ID | Appends files to the session ID | Commits each part of the file to the session ID | Updates items | Retrieves item notes

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. 

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.
  • 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:  
  1. The file will be renamed and saved to the location defined in the PhysicalDocPath Customization Key.
  2. The request will be updated with the file's name and document type.
  3. 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.  

Appends files to the session ID

 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: 
    • File data, up to the MaxAppendSize received in the Create Upload Session response message(s). 
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 CurrentStatus and CurrentStatusDate fields. These fields can only be updated for an item using the route items endpoint.

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 valu
  • 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

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. More information on API keys is available at Configuring the Ares Web Platform. 

The Base WebService URL isn't relevant for the API so you can just enter the API URL: https://yourservername.ares.atlas-sys.com/ares/api/.

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!

 

Questions?

If this article didn’t resolve your issue, please contact Atlas Support for assistance:

Contact Support

Articles in this section