1. Atlas Systems
  2. Ares
  3. General

Ares API

Print Friendly and PDF Follow

Avatar
Sara Juel
Updated

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 URL specified in the ApiConfig table. This should be the base webserver URL plus "/webapi/". The record in the ApiConfig table is created automatically by the Ares Updater for new installs. 
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 values. 
 

Swagger Documentation   

The Are 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. 
 

Available Endpoints 

The syntax for the Ares API is in the following format: https://{your-ares-api-url}/{endpoint}. Please replace 'servername' with the IP address or DNS and 'endpoint' with one of the following endpoints listed below. For example, https://atlas-sys.com/loanperiods.      

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.     

Users

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

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. 
 
 

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.
 
 

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 the following item fields: 
    • CourseId
    • ActiveDate
    • InactiveDate
    • ProcessingLocation
  • The endpoint will validate the new item with the fields established in the JSON body. 

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.

 

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/{itemid}/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.  

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

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.
 

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 take a moment and answer a few questions to help improve our documentation:

Feedback

Articles in this section