Learning Manager API
The Learning Manager API is based on principles of REST, and exposes key elements of the Learning Manager Object Model to application developers through HTTP. Before knowing the details of the API endpoints and the HTTP methods, developers can become familiar with the various Learning Manager objects, their attributes and inter-relationships. Once the models are understood, it will be useful to get a basic understanding of the structure of API requests and responses, and a few common programming terms that we use generically across the API.
For details of the various API endpoints and methods, refer to the Learning Manager API documentation.
Learner APIs
Adobe Learning Manager - Learner APIs allow you to create a custom learning experience for your users. The usage of these APIs need a valid user token and are to be used only for the purpose of workflows where there is a fully licensed/registered Learner.
The non-logged in use cases require special handling.
Reach out to the Solution Architecture team, in case you have any questions on the appropriate use of these APIs and ensure that a Solution Architect has vetted a solution before you deploy it.
API authentication
When writing an application that makes API calls to Learning Manager, you have to register your application using the Integration Admin app.
Learning Manager APIs use OAuth 2.0 framework to authenticate and authorize your client applications.
Procedure
1. Set up your application
You can set up your application with client id and client secret to use the proper end points. Once you register your application, you can get the clientId and clientSecret. Get URL should be used in browser as it authenticates the Learning Manager users using their pre-configured accounts such as SSO, Adobe ID, and so on.
GET https://learningmanager.adobe.com/oauth/o/authorize?client_id=<Enter your clientId>&redirect_uri=<Enter a url to redirect to>&state=<Any String data>&scope=<one or more comma separated scopes>&response_type=CODE.
After successful authentication, your browser redirects to the redirect_uri mentioned in the above URL. A parameter code is appended along with the redirect uri.
2. Get refresh token from code
POST https://learningmanager.adobe.com/oauth/token Content-Type: application/x-www-form-urlencoded
Body of the post request:
client_id:
<enter your clientid>
&
client_secret:
<enter your clientsecret>
&
code:
<code from step 1></code>
</enter>
</enter>
3. Obtain an access token from refresh token
URL to obtain access token:
POST https://learningmanager.adobe.com/oauth/token/refresh Content-Type: application/x-www-form-urlencoded
Body of the post request:
client_id:
<enter your clientid>
&
client_secret:
<enter your clientsecret>
&
refresh_token:
<refresh token>
</refresh>
</enter>
</enter>
URL to verify access token details
GET https://learningmanager.adobe.com/oauth/token/check?access_token=<access_token>
Usage limitation
An access token is valid for seven days. After a day, you have to generate a new access token using refresh token. If you generate a new access token from refresh token while an existing access token is still valid, the existing token is returned.
Some of the frequently used terms in Learning Manager API are explained below for your reference.
Includes
Developers can access a single API object model and also multiple models associated with that model. To access the subsequent related models, you need to understand the relationship of each model with other models. Includes parameter enables developers to access the dependant models. You can use comma separator to access multiple models. For sample usage and more details on includes, refer to sample API model section in this page.
API request
The API requests can be made by making a HTTP Request. Depending upon the end point and method developer may have a choice of various HTTP verbs such as GET, PUT, POST, DELETE, PATCH, etc. For some requests query parameters can be passed. When making a request for a specific data model, the user can also request for related models as described in the JSON API specifications. The structure of a typical API Request is described in sample model usage.
API response
When an API request is made by a client, a SON document is obtained according to the JSON API specification. The response also contains the HTTP Status code, which the developer can verify to perform the appropriate next steps in his application logic. The structure of a typical API Response is described in sample model usage.
Errors
When an API request fails, an Error response is obtained. The HTTP Status code returned in the response indicates the nature of error. Error codes are represented with numbers for each model in the API reference. 200, 204, 400 and 404 are some of the common errors represented in APIs indicating HTTP access issues.
Fields
API object’s attributes and its relationships are collectively called Fields. Refer to JSON API for more information. You can use Fields as a parameter while making API calls to fetch one or more specific attributes from the model. In absence of the Fields parameter, the API call fetches all the available attributes from the model. For example, in the following API call, fields[skill]=name fetches you the name attribute of the skill model alone.
https://learningmanager.adobe.com/primeapi/v2/users/{userId}/userSkills/{id}?include=skillLevel.skill&fields[skill]=name
Pagination
Sometimes, an API request results in a long list of objects to be returned in the response. In such cases, the pagination attribute enables the developer to fetch the results sequentially in terms of multiple pages, where each page contains a range of records. For example, pagination attribute in Learning Manager enables you to set the maximum number of records to be displayed in a page. Also, you can define the range value of records to be displayed on page.
Sorting
Sorting is allowed in API models. Based on the model, choose the type of sorting to be applied for the results. Sorting can be applied in ascending or descending order. For example, if you specify code sort=name
, then it is ascending sort by name. If you specify code sort=-name
, it is descending sort by name. Refer to JSON API spec for more information.
API usage illustration
Let us consider a scenario where a developer wants to get skill name, max points assigned for skill level and points earned by the learner for that skill.
A userSkill model in Learning Manager APIs consists of id, type, dateAchieved, dateCreated, pointsEarned as default attributes. So, when a developer uses GET method to acquire details of userSkill model, the current data pertaining to the default attributes is shown in the response output.
But, in this scenario, the developer wants to get the skill name, and points of skill level for the user. Learning Manager API enables you to access this related information using relationship fields and include parameter. The associated models for userSkill are obtained in relatioships tag. You can get the details of each associated models by calling these models along with the userSkill. To get this information, use code include
parameter with dot (period) separated values for each of the associated models. You can use comma as separator to request another model like user include=skillLevel.skill,course
API Call
https://learningmanagerqe1.adobe.com/primeapi/v1/users/%7buserId%7d/userSkills/%7bid%7d?include=skillLevel.skill&fields%5bskill%5d=name&fields%5bskillLevel%5d=maxCredits&fields%5buserSkill%5d=pointsEarned
For example userId can be 746783 and the userSkills id: 746783_4426_1.
Response of API call
\{
"links": {"self": "https://learningmanager.adobe.com/primeapi/v2/users/746783/userSkills/746783_4426_1?include=skillLevel.skill&fields[userSkill]=pointsEarned&fields[skillLevel]=maxCredits&fields[skill]=name"},
"data": {
"id": "746783_4426_1",
"type": "userSkill",
"attributes": {"pointsEarned": 5},
"links": {"self": "https://learningmanager.adobe.com/primeapi/v2/users/746783/userSkills/746783_4426_1"}
},
"included": [
{
"id": "4426",
"type": "skill",
"attributes": {"name": "Java"},
"links": {"self": "https://learningmanager.adobe.com/primeapi/v2/skills/4426"}
},
{
"id": "4426_1",
"type": "skillLevel",
"attributes": {"maxCredits": 10}
}
]
}
Learning Manager models
The Learning Manager API allows developers to access Learning Manager objects as RESTful resources. Each API endpoint represents a resource, typically an object instance like Badge, or a collection of such objects. The developers then use the HTTP verbs such as PUT, GET, POST and DELETE to perform the CRUD operations on those objects (collections).
V1 API
The following diagram represents the various elements of the Learning Manager Object Model in V1 API.
The following table describes various elements of the Learning Manager V1 object model:
V2 API
Following are the various elements of the Learning Manager class diagram in V2 API.
List of object attributes and relationships.
account
Attributes
dateCreated
gamificationEnabled
id
locale
loginUrl
logoUrl
name
subdomain
themeData
timeZoneCode
Relationships
contentLocales(localizationMetadata)
gamificationLevels(gamificationLevel)
timeZones(timeZone)
uiLocales(localizationMetadata)
badge
id
imageUrl
name
state
catalog
dateCreated
dateUpdated
description
id
isDefault
isInternallySearchable
isListable
name
state
data
id
names
gamification
color
name
points
learningObject
Attributes
authorNames
dateCreated
datePublished
dateUpdated
effectivenessIndex
enrollmentType
id
imageUrl
isExternal
isSubLoOrderEnforced
loType
state
tags
Relationships
authors(user)
enrollment(learningObjectInstanceEnrollment)
instances(learningObjectInstance)
prerequisiteLOs(learningObject)
skills(learningObjectSkill)
subLOs(learningObject)
supplementaryLOs(learningObject)
supplementaryResources(resource)
learningObjectInstance
Attributes
completionDeadline
dateCreated
enrollmentCount
id
isDefault
seatLimit
state
validity
Relationships
badge(badge)
l1FeedbackInfo(feedbackInfo)
learningObject(learningObject)
loResources(learningObjectResource)
localizedMetadata(localizationMetadata)
subLoInstances(learningObjectInstance)
learningObjectInstanceEnrollment
Attributes
dateCompleted
dateEnrolled
dateStarted
hasPassed
id
progressPercent
score
state
Relationships
learner(user)
learnerBadge(userBadge)
learningObject(learningObject)
loInstance(learningObjectInstance)
loResourceGrades(learningObjectResourceGrade)
learningObjectResource
Attributes
externalReporting
id
loResourceType
resourceType
version
Relationships
learningObject(learningObject)
loInstance(learningObjectInstance)
localizedMetadata(localizationMetadata)
resources(resource)
learningObjectResourceGrade
Attributes
dateCompleted
dateStarted
dateSuccess
duration
hasPassed
id
progressPercent
score
Relationships
loResource(learningObjectResource)
learningObjectSkill
credits
id
Relationships
learningObject(learningObject)
skillLevel(skillLevel)
recommendation
Attributes
id
reason
Relationships
learningObject(learningObject)
resource
authorDesiredDuration
completionDeadline
contentStructureInfoUrl
contentType
contentZipSize
contentZipUrl
dateCreated
dateStart
desiredDuration
downloadUrl
extraData
hasQuiz
hasToc
id
instructorNames
isDefault
locale
location
name
onlyQuiz
reportingInfo
reportingType
seatLimit
skill
Attributes
description
id
name
state
Relationships
levels(skillLevel)
skillLevel
id
level
maxCredits
name
Relationships
badge(badge)
skill(skill)
user
Attributes
avatarUrl
bio
contentLocale
email
fields
id
name
pointsEarned
profile
roles
state
timeZoneCode
uiLocale
Relationships
account(account)
manager(user)
userBadge
Attributes
assertionUrl
dateAchieved
id
modelType
Relationships
badge(badge)
learner(user)
model(learningObject)
userCalendar
Attributes
course
courseType
dateStart
enrolled
id
month
quarter
Relationships
containerLO(learningObject)
course(learningObject)
userNotification
actionTaken
channel
dateCreated
id
message
modelIds
modelNames
modelTypes
read
role
userSkill
Attributes
dateAchieved
dateCreated
id
pointsEarned
Relationships
learnerBadge(userBadge)
learningObject(learningObject)
skillLevel(skillLevel)
user(user)
Application development process
Pre-requisites
As a developer you have to create a trial account on Learning Manager, so that you can have full access to all the roles within that account. To be able to write an application, a developer has to create some users and courses and get the account to a reasonable state so that the application being developed can have access to some sample data.
Create client id and secret
-
In Integration Admin login, click Applications on the left pane.
Select Applications on Integration Admin
-
Click Register at the upper-right corner of the page to register your application details. Registration page appears.
Register the application
It is mandatory to fill up all the fields in this page.
Application Name: Enter your application name. It is not mandatory to use the same application name, it can be any valid name.
URL: If you know the exact URL where the application is hosted, you can mention it. If you are not aware, then you can mention your company URL. Valid URL name is mandatory in this field.
Redirect Domains: Enter the domain name of the application where you want the Learning Manager application to redirect after OAuth authentication. You can mention multiple URLs here but you have to use the valid URLs such as
http://google.com
,http://yahoo.com
and so on.Description: Enter the brief description for your application.
Scopes: Choose one of the four available options to define the scope of your application. Based on your choice mentioned here, Learning Manager API endpoint are accessible for your application. For example, If you chose Learner role read access, then all the Learning Manager learner API end points are read-only accessible to your application.
For this account only?
Yes - if you choose Yes, then the application is not visible to other account administrators.
No - if you choose No, other account admins can also access this application but they need to use the application id to access this application. Application id is generated and displayed in Learning Manager application Edit mode.If you choose Admin role read and write access as scope while registering the application and choose Admin role read access while authoring the APIs, you can still have write access for the application as the app registration scope supersedes the authorization workflow.
-
Click Register at the upper-right corner after filling up the details in the registration page.
Application development and testing
The Learning Manager API can be used by developers to build any application. Developers have to ensure that their accounts consist of some valid users and courses. They can create a few dummy users and courses and simulate activity in the trial account, so that they can test functionality of the application.
Application deployment
We recommend that the Learning Manager Administrator or an Integration Administrator for the production account, to take ownership of making the application available to users within their organization. Once the application has been tested and is considered ready for production, inform the administrator of the production account. Ideally, the administrators want to generate a new client-id and client-secret for the application in the production account, and perform the necessary steps to incorporate them inside the application in a secure manner. The actual procedure for deploying applications varies from enterprise to enterprise, and the Learning Manager Administrator of your organization has to take support from the IT/IS department within your organization to complete the deployment.
External application approval
You can add external applications by clicking Approve at the upper-right corner of the Applications page. Provide the external application id and click Save.
Add and approve an external application