This guide provides an introduction to Watershed's Administration APIs, some generic information that applies to several API resources and links to guides relating to specific aspects of the API.
APIs Overview
People API
Please note: It is normally preferable to import people as a CSV file (possibly via the CSV Upload API), rather than directly interacting with the People API.
The Watershed People API is used by activity providers to associate multiple personas as a single person.
Related:
Groups API
Please note: It is normally preferable to import groups as a CSV file (possibly via the CSV Upload API), rather than directly interacting with the Groups API.
The Groups API enables outside HR systems or employee data record systems to import and modify data about the people and groups in your organization. Examples of data that can be imported include:
- Organizational hierarchy (e.g., teams, divisions, regions)
- Functional groups (e.g., managers, sales staff, production staff)
- Location-based groups (e.g., United States, Europe, Asia)
- Any other flat or hierarchical set of groups
Group information can be used in any of the reports provided by Watershed, such that aggregated data can be filtered, categorized, or sorted according to groups.
Permissions API
Please note: It is normally preferable to import data permissions as a CSV file (possibly via the CSV Upload API), or to assign permissions to groups via the UI and manage those groups via CSV, rather than directly interacting with the Permissions API.
Dashboard, measure and Report Builder permissions cannot be set via CSV import, however they can be assigned to groups which are managed by CSV import.
The Watershed Permission API is used to permit access to data, dasboards, measures and Report Build. The data permissions set are then automatically used across all reporting capabilities.
Related:
Dashboards API
Our Dashboard API allows outside applications to save and organize reports using dashboards and reports while also allowing users to see these reports in the Watershed interface. With this API, for example, an integrated application can create a new activity report for the most active courses in its library or manage dashboards for each group of users present in the application.
Related: Dashboard API
Credentials API
The Watershed Credentials API is used to create and manage LRS and Watershed API credentials. This can be used, for example, by an application such as an LMS that provides LRS credentials for launched e-learning courses. In that scenario, a set of credentials can be created for the launch session and then deleted some time after, when the session is complete.
Related: Credentials API
Common Features of Administration APIs
Please note: These features are not supported by the APIs used to pull data out of Watershed (the Aggegration API and Data Export API). They are only supported for the Administration APIs listed on this page.
Collections and Paging
Many resources, when responding to a GET request, will return results in the form of a collections object.
|
Property |
Type |
Description |
|
count |
Integer |
The number of records matching the filter. |
|
results |
Array |
An array of results returned. |
These endpoints, in addition to the parameters listed in their documentation, also support parameters that can be used for paging.
|
Parameter |
Type |
Description |
|
_limit |
Integer |
The maximum number of items to include in the collection’s results array. Limit defaults to 100 and has a maximum of 1000. |
|
_offset |
Integer |
The index of the first item to include in the collection's results array. Defaults to 0. |
Please note: some resources return a simple array rather than a collection object. These resources do not support the _limit and _offset parameters. See the documentation for individual resources.
Searching and sorting
Some resources support query parameters that can be used to match against when making a GET request. See the documentation for individual resources for available parameters. Normal behavior of these parameters is to search for exact matches, however any query parameter can be prefixed with in_ to enable partial matches. For example, in_description="course" would return records where the description contained the word “course”.
It’s also possible to sort results using the order_by parameter. The value of this parameter is any property of the object being requested which contains a string or integer value. For example, you can request people by id, name or created. You can’t order people by personas because the personas property contains an array.
Results are ordered ascending by default. Results can be ordered descending by prepending “-” to the sort property’s name. The order_by parameter can contain a single property to sort by or a comma separated list.
For example, order_by="name,-id" will first sort by name in ascending order, then sort by id in descending order.