Ares API

Print Friendly and PDF Follow

These release notes describe functionality that may not have been released yet. To see when this functionality is planned to release, please review What's new and planned for Ares. Delivery timelines and projected functionality may change or may not ship. 

Features

Method

Endpoint

 

Lookup

Update 

Create

Items

Users

Courses

Enrollment by configurable identifier

API Calls

Users

Get(username) : User 

Allows for looking up the user by username. If the username exists in UserValidation and not in Users, the user will be auto-created. Corresponding entries in the CourseUserValidation table will be added to the CourseUser table, including the overwriting of the ValidationUser entry if a pre-existing course had no instructor.

GetByExternalIdentifier(externalID) : User

Allows for looking up the user or username by an external ID. The field this function should check is configured per API key in the APIConfig table. If the username exists in UserValidation and not in Users, the user will be auto-created. Corresponding entries in the CourseUserValidation table will be added to the CourseUser table, including the overwriting of the ValidationUser entry if a pre-existing course had no instructor.

GetCourses(Username, optional Available) : List<Course>

Provides an “available” search filters based on the user-provided. For students, this will be based on the course’s StartDate and StopDate.  For instructors, this will be based on the course semester’s ItemAdditionDate and the course’s StopDate.  Start and stop dates for both scenarios should be calculated based on the existing start and stop date override rules. 

Courses

Get(optional parameters active, editable) : List<Course>

Returns all courses. Provides "active" and "editable" search filters. 

Get(CourseID) : Course

Allows for looking up the course by CourseID.

GetByExternalIdentifier(externalID) : Course

Allows for looking up a course by an external ID. The field this function should check is configured per API key in the APIConfig table.

GetItems(CourseID, optional Available) : List<Item>

Returns all items based on the CourseID provided. It provides an "available" search filter based on the CurrentItemStatus. 

Items

Get(ItemID) : Item

Allows for looking up an item by ItemID.

Post(Item) : Item

Adds the item to the course.

Route(ItemID, RouteArguments)

Allows for the updating of CurrentItemStatus by ItemID.

Use Case

Example Use Case 1

I know what ITEM I want
and the CITATION is in Primo
and I know what COURSE I want to add it to

— or —

I know what ITEM I want
but the CITATION is NOT in Primo
and I know what COURSE I want to add it to

Caveat: This use case expects that potential instructors already exist or are being loaded into UserValidation.

Example Use Case 2

I know what ITEM I want
and it's in the CATALOG
but the item is CHECKED OUT

Caveat: This use case expects that potential instructors already exist or are being loaded into UserValidation.

Example Use Case 3

I want to seee what I've ALREADY REQUESTED (as opposed to all the items for the courses that a user has instructor-level permissions)

Caveats

  • If you are using Ares Authentication with UserValidation and not populating user passwords, users created by the API (via Lookup Username endpoints) will not be able to log into the DLL until their passwords have been reset by staff or reset using the Forgot Password Ares web page.
  • Lookups by CourseID or mapped identifier will NOT include results from course validation. Sites should enable Course Management to automatically create courses if they need all courses to be returned by the course lookup endpoints.

Impact

  • InternalMappingField added to APIConfig table.
  • You will first need to generate an API Key for your application and create an entry in the WebPlatformConfig table in the Ares Customization Manager. An API Key is required for all secured methods. See Configuring the Ares Web Platform for more information.
  • In order for the Web Platform to work properly and to maintain security, you must have a valid SSL certificate and support HTTPS. Adding the AllowInsecureWebPlatformRequests will determine if the requests require SSL.
  • The Ares Web Platform cannot be protected by remote auth filters. These will impede the web traffic that needs to flow freely to and from the web platform. 

 

Questions?

If this article didn’t resolve your issue, please take a moment and answer a few questions to help improve our documentation:

Feedback