The Aeon API allows developers to perform actions in Aeon and build integrations outside of the installed Aeon components. For example, the API allows the developers to connect to the database and change a transaction status.
Installation | Aeon API URL | Swagger Documentation | OData Support | Available Endpoints | Authentication | Additional Information
Installation
Using the Aeon API requires Aeon version 4+. Certain Microsoft .NET components must also be installed on the Aeon Server. These components are provided by Microsoft and will need to be installed separately as they are not included in the default Aeon installation:
- Aeon 5.2+: The Aeon API requires the .NET Core components at version 2.2 or higher and the Microsoft ASP.NET Core 2.2 Runtime bundle (download from Microsoft's website). These installers are provided by Microsoft and must be run separately.
- Aeon 5.1 and earlier: The Aeon API requires the .NET Core components at version 2.1 or higher. This installer is provided by Microsoft and must be run separately.
Note: As of v5.1, the Aeon API is installed by default during the server installation/update process and does not need to be installed separately. However, the .NET Core components are not part of the default Aeon install and will still need to be installed separately.
For older versions of Aeon, the latest installer for the Aeon Web API is available on the Aeon Downloads page.
Please contact Atlas Systems at 1-800-567-7401 x1 or support@atlas-sys.com for the credentials to download the installer.
Service hours are Monday through Friday 8am-5pm eastern time, excluding Federal holidays.
Aeon API URL
For standard Aeon installations, the default URL for the Aeon API is https://servername/aeon/api/. However, your path to the API may differ if using a non-standard installation path for the Aeon API on your Aeon server.
Swagger Documentation
The Aeon API has developer-oriented documentation built-in. You can get to the API Swagger documentation at https://servername/aeon/api/swagger/.
*Replace 'servername' with the IP address or DNS.
OData Support
OData query options are available to help filter result data for select Aeon API endpoints that return a list of objects. OData is currently only supported for the Get Users endpoint.
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.'
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 |
Example
Return users with email addresses ending in "gmail.com":
GET /<API URL>/Users?$filter=endswith(eMailAddress, '@gmail.com')
Pagination
OData pagination can be added to the query to limit the number of results returned by the endpoint using the following parameters:
skip | Specifies the number of items in the queried collection that are to be skipped and not included in the result |
---|---|
top | Specifies the number of items in the queried collection to be included in the result |
Examples
Return a list of the first 100 users:
GET /<API URL>/Users?$top=100
Return a list of users 101-200 (i.e., skipping the first 100 results):
GET /<API URL>/Users$top=100&skip=100
Return a list of users 201-300 (i.e., skipping the first 200 results):
GET /<API URL>/Users?$top=100&skip=200
Available Endpoints
Custom Fields | Queues | Reading Rooms | Requests | System Information | Token | Users
Custom Fields
Retrieve custom fields by context type
Get | /api/customFieldDefinitions/{contextType} | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Returns a list of custom fields defined for the specified context type. Parameters:
Click for properties of the information returned
Custom Fields Support in Other EndpointsTo include custom fields when creating a request via the POST Request endpoint, the Request JSON object must have a property named "CustomFieldsValues" containing all custom field values that will be supplied in the "ShortName:value" format. Response objects returned by the GET Request and POST Request endpoints and user objects returned by the GET User endpoint will contain a CustomFields property listing all defined fields for the given request, in the same "ShortName:value" format. Null values will be included. |
Queues
Retrieve queues | Retrieve a specific queue | Retrieve requests within a specific queue
Retrieve queues
Get | /api/Queues |
---|---|
Returns queues configured in Aeon. |
Retrieve a specific queue
Get | /api/Queues/{id} |
---|---|
Returns a Queue identified by ID. |
Retrieve requests within a specific queue
Get |
/api/Queues/{id}/requests |
---|---|
Returns requests associated with the queue identified by ID. |
Reading Rooms
Retrieve reading rooms | Retrieve a specific reading room | Retrieve closures for a specific reading room | Retrieve available appointment times for a specific reading room and date
Retrieve reading rooms
Get | /api/ReadingRooms | ||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Returns a list of reading rooms configured for appointment scheduling in Aeon. Parameters:
Click for properties of the information returned
|
Retrieve a specific reading room
Get | /api/ReadingRooms/{id} | ||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Returns information on a specified reading room identified by ID. Parameters:
Click for properties of the information returned
|
Retrieve closures for a specific reading room
Get |
/api/ReadingRooms/{id}/Closures |
---|---|
Returns a list of full closures for the specified reading room, limited to those occurring in the future. This endpoint reports both full closures (i.e. "Closed" exception types) and "partial" closures (i.e. "Reduced Availability" exception types) that reserve a number of seats greater than or equal to the reading room's total available seats. Parameters:
|
Retrieve available appointment times for a specific reading room and date
Get |
/api/ReadingRooms/{id}/AvailableAppointments/{date} |
||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Returns a list of available appointment times for the specified reading room on the specified date. Note: This endpoint will ignore appointments with a status of Cancelled when determining the appointment availability for the room.
Parameters:
*Aeon 5.2 only Click for properties of the information returned
|
Requests
Retrieve a specific request | Retrieve next steps for a specific request | Create a new request | Route a request to a new status | Retrieve valid routing statuses for a request | Retrieve requests associated with a barcode | Reshelve request by barcode | Add note to a request | Retrieve notes for a specific request | Update request information
Retrieve a specific request
Get | /api/Requests/{id} |
---|---|
Returns a request identified by transaction number.
|
Retrieve next steps for a specific request
Get | /api/Requests/{id}/nextsteps |
---|---|
Returns next step process names for the transaction identified by ID. |
Create a new request
Post | /api/Requests/create/ |
---|---|
Creates Aeon requests for a specified user. API Call: At a minimum the username (user must be a valid user in the database) must be supplied; however, additional user information may be provided if supplied by the appropriate corresponding database column names.
Additional Notes
Example Call:
|
Route a request to a new status
Post
|
/api/Requests/{id}/route |
---|---|
Routes a transaction to the given transaction or photoduplication status. Routing rules will be applied. |
Retrieve valid routing statuses for a request
Get | /api/Requests/{id}/routes |
---|---|
Returns a list of the valid transactions and photoduplication queues a request may be routed to. |
Retrieve requests associated with a barcode
Post | /api/Requests/Batch/?{parameters} |
---|---|
Returns a list of requests for the given barcode. Unlike the RequestBarcodes/Reshelved endpoints, the endpoint allows for nonstandard characters. API Call:
|
Reshelve request by barcode
Post | /api/Requests/Batch/Reshelved |
---|---|
Reshelves request based on the given barcode. Unlike the RequestBarcodes/Reshelved endpoints, the endpoint allows for nonstandard characters. API Call:
|
Add note to a request
Post | /api/Requests/{transactionNumber}/notes |
---|---|
Adds a note to an existing request. Parameters (required):
API Call:
Example Call:
Example Response:
|
Retrieve notes for a specific request
Get | /api/Requests/{transactionNumber}/notes |
---|---|
Returns a list of notes associated with a specified request. Parameters (required):
Example Response:
|
Update request information
Patch | /api/Requests/{id} |
---|---|
Used to update information for a specific request. API Call:
Example Call: The following example will set the ItemAuthor field to Doe, John, the ItemVolume field to 456, the ItemTitle field to null, the ItemInfo5 field to ItemInfo, and a Transaction type custom field defined in the CustomFieldDefinitions table with the short name Container3 to Custom:
Additional Notes:
Response: The endpoint can return the following responses:
|
Post | /api/RequestBarcodes/{barcode}/reshelved |
---|---|
The RequestBarcode endpoints have been replaced by the Requests/Batch endpoints and are now considered deprecated.
Reshelves request based on the given barcode. API Call:
|
Post |
/api/RequestBarcodes/{id}/reshelved |
---|---|
The RequestBarcode endpoints have been replaced by the Requests/Batch endpoints and are now considered deprecated.
Reshelves request based on a given transaction number. API Call:
|
System Information
Retrieve Web API version
Get | /api/SystemInformation/Version |
---|---|
Returns the version of the Web API.
|
Token
Retrieve authentication token
Post | /api/Token |
---|---|
Retrieves an authentication token for the provided staff credentials.
|
Users
Retrieve a list of users | Retrieve a specific user | Retrieve requests for a specific user | Retrieve appointments for a specific user
Retrieve a list of users
Get | /api/Users |
---|---|
This endpoint supports OData filtering.
Retrieves a list of all users up to a maximum of 2000 results. The maximum number of users that can be retrieved by this endpoint is 2000. OData filtering and pagination can be used to limit the number and specify the type of user results returned by the endpoint. Note that custom fields defined in the CustomFieldDefinitions table are not supported for use with OData filters, but will be returned by the endpoint in the results.
|
Retrieve a specific user
Get | /api/Users/{username} |
---|---|
Returns a user identified by username.
|
Retrieve requests for a specific user
Get
|
/api/Users/{username}/requests
|
---|---|
Retrieves a list of all requests (or active requests only if the ActiveOnly parameter is used) for a specific user.
|
Retrieve appointments for a specific user
Get
|
/api/Users/{username}/appointments
|
---|---|
Returns a JSON object containing the list of appointments for a given user. The appointment object also contains the associated reading room object. Parameters:
|
Authentication
Most of the actions will require authentication. There are 2 ways to authenticate in the Aeon API: Aeon API Key or staff tokens.
API Key
You can create an API key in the Aeon Customization Manager. More information on API keys is available at Configuring the Aeon Web Platform.
The Base Webservice URL isn't relevant for the API so you can just enter the API URL: https://yourservername.aeon.atlas-sys.com/aeon/api/.
Staff Token
The staff tokens will use the POST Token operation where you'll post an Aeon staff username and password. It will return a token which should be used as a BEARER authentication header.
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-AEON-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!