Introduction

This page will guide you through using the It’s Learning API written in modern ES6. The API is available on NPM and GitHub.

ItsLearning

To use the API, you must first include it

const ItsLearning = require('itslearning');

To access further functionality, you must first find an organisation to work with. The API exports two methods, searchOrganisation and fetchOrganisation.

Search for organisations

Searching for an organisation

ItsLearning.searchOrganisation('Blekinge Tekniska Högskola')
  .then(matches => {
    console.log(`A match was: ${matches[0].name} with the id ${matches[0].id}`);
  }).catch(error => {
    // there was an error with the request
  });

Takes

Parameter	Default	Description
query	required	The partial name of an organisation to search for.

Returns Promise

Resolve

List of organisations.

Property	Description
id	numeric id of organisation.
name	The name of the organisation.

Reject

Error reflecting cause.

Fetching an organisation

Fetching an organisation

ItsLearning.fetchOrganisation(640)
.then(organisation => {
  // organisation is an instance of Organisation
}).catch(error => {
  // there was an error with the request
});

Takes

Parameter	Default	Description
id	required	The numeric id for the organisation to fetch.

Returns Promise

Resolve

Organisation object.

Reject

Error reflecting cause.

Organisation

An organisation is retrieved when calling ItsLearning.fetchOrganisation successfully. The object contains a series of properties.

Property	Description
name	The name of the organisation.
shortName	A shorter name for the organisation. May be `null`.
id	The numeric id of the organisation.
url	A url to the organisation’s It’s Learning site.

console.log(`Organisation '${organisation.name}' (${organisation.shortName}) has id '${organisation.id}' and url '${organisation.url}'``);

To access further functionality, one must authenticate as a user of the organisation. THis is done by calling the authenticate function.

Authenticating as a user

Authenticating

organisation.authenticate('username', 'password')
.then(user => {
  // further use
}).catch(error => {
  // there was an error with the request
})

Takes

Parameter	Default	Description
username	required	The username to use when authenticating.
password	required	The password to use when authenticating.

Returns Promise

Resolve

User object.

Reject

Error reflecting cause.

User

A user is retrieved when authenticating successfully. The object contains a series of properties.

Property	Availability	Description
id	always	The numeric id of the user.
firstName	after .fetchInfo()	The user’s first name.
lastName	after .fetchInfo()	The user’s last name.
language	after .fetchInfo()	The user’s language.
profileImage	after .fetchInfo()	A URL to the user’s profile image. May be `null`.
calendar	after .fetchInfo()	A URL to the user’s personal calendar.
authenticated	always	A bool indicating whether or not the user is currently authenticated.

Fetching personal information

Fetching info

user.fetchInfo()
.then(() => {
  // the user object has been updated. All properties are now available
}).catch(error => {
  // there was an error with the request
});

Returns Promise

Resolve

undefined

Reject

Error reflecting cause.

Fetching unread messages count

Fetching unread messages count

user.fetchUnreadMessagesCount()
.then(count => {
  console.log(`There are ${count} unread messages`);
}).catch(error => {
  // there was an error with the request
});

Returns Promise

Resolve

Numeric value indicating count.

Reject

Error reflecting cause.

Fetching unread notifications count

Fetching unread notifications count

user.fetchUnreadMessagesCount()
.then(count => {
  console.log(`There are ${count} unread notifications`);
}).catch(error => {
  // there was an error with the request
});

Returns Promise

Resolve

Numeric value indicating count.

Reject

Error reflecting cause.

Fetching notifications

Fetching notifications count

user.fetchNotifications()
.then(notifications => {
  // further use of the notifications
}).catch(error => {
  // there was an error with the request
});

Returns Promise

Resolve

List containing notifications objects.

Property	Description
id	The numeric id of the notification.
text	Text content of the notification.
date	Date when the notification was published.
author	Object containing information about the author.
type	Type of notification. Values include ‘Assessment’.
url	A URL to the notification.
content	A URL to the content of the notification.
isRead	A boolean value representing whether or not the notification has been read.

Property	Description
id	The numeric id of the author.
firstName	The author’s first name.
lastName	The author’s last name.
profile	A URL to the author’s profile
profileImage	A URL to the author’s profile image. May be `null`.

Reject

Error reflecting cause.

Fetching news

Fetching unread notifications count

user.fetchNews()
.then(news => {
  // further use of the news
}).catch(error => {
  // there was an error with the request
});

Returns Promise

Resolve

List containing news objects.

Property	Description
id	The numeric id of the news.
location	Location of the news within the organisation.
text	Text content of the news.
date	Date when the news was published.
author	Object containing information about the author.
type	Type of news.
contents	Object containing contents.
isRead	A boolean value representing whether or not the notification has been read.

Property	Description
id	The numeric id of the author.
firstName	The author’s first name.
lastName	The author’s last name.
profile	A URL to the author’s profile
profileImage	A URL to the author’s profile image. May be `null`.

Property	Description
id	The numeric id of the content.
text	Text of the message. May be `null`.
url	A URL to the message. May be `null`.

Reject

Error reflecting cause.

Fetching comments to news

Fetching comments to news

user.fetchComments(NEWS_ID)
.then(comments => {
  // further use of the comments
}).catch(error => {
  // there was an error with the request
});