Using Watershed's Administration APIs

 Related: This section explains how to use Watershed's APIs for administration. Watershed also offers APIs for storing and retrieving data.

Watershed is a learning analytics platform that provides actionable insights from your training and performance data. Built using modern practices for data processing and cloud-based platforms, we provide several APIs that allow you to integrate Watershed with external applications.

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.

Who can use this feature?
 User Types
Global Admins can create credentials for use with the API.
 Pricing
Available on CLO and Enterprise pricing plans.
 Expertise
Experts can use this feature.

Connecting to Watershed’s API

Our family of REST APIs are made accessible through a secure SSL connection over HTTP, using basic authentication. To connect to Watershed’s API you need a set of credentials and organization id (unless you are creating an organization, then you don’t need the id).

To create a set of credentials, see How do I add an activity provider to Watershed? You are able to choose if credentials have access to the LRS API, the Reporting API or both.

This is passed to the API using Basic HTTP Authentication. In addition to the Authorization header required for Basic Authentication, all POST and PUT requests must have a Content-Type header with the value application/json.

The easiest way to find the organization id is to log in to Watershed and go to the Settings/Data page. The organization id is included within the Watershed LRS Endpoint URL. For example if the endpoint URL is https://watershedlrs.com/api/organizations/1234/lrs/ then the organization id is 1234.

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.

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.

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.

 RelatedDashboard 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.

 RelatedCredentials 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.

 

Was this article helpful?
1 out of 2 found this helpful

If you can't find what you need or you want to ask a real person a question, please contact customer support.