Installation
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.
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
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
Retrieves user details for a given username
GET | /Users/{username} |
---|---|
Retrieves user details for a given external user ID |
|
GET | /Users/ExternalUserId/{id} |
API Call:
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:
Retrieves courses associated with a given username |
|
GET
|
/Users/{username}/courses — or — /Users/{username}/courses?activeCourses=true |
API Call:
Response:
|
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
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:
|
Items
Creates new items
POST | /Items |
---|---|
Used to create new item records in Ares.
API Call:
Response:
Route items |
|
POST | /Items/{id}/Route |
Used to route items to new statuses.
API Call:
Response:
Downloads item files |
|
GET
|
/items/{item id}/downloadfile?FileType={Item or PermissionsDocument} |
Used to download files.
API Call:
Response:
Deletes items |
|
DELETE | /items/{item id}/delete |
Used to delete files.
API Call:
Response:
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:
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:
Response: The response may include one or more of the following:
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:
Response:
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:
|
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.
|
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!