Atlantis Learning Management System (LMS) API
Copyright 2017 Atlantis Learning Community
Unless required by applicable law or agreed to in writing, software distributed under this License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
Please send all feedback and inquiries to info@atlantislearningcommunity<
Table of Contents
- How to Use This Document
- Data Flow in ALMS API
- Agent and Persona Management
- Extending xAPI
- Profiles, Vocabularies, and Learning Communities
The ALMS API is a technical specification that aims to facilitate the documentation and communication of learning experiences across multiple “Learning Communities.”
It specifies a structure to describe learning experiences and defines how these descriptions can be exchanged.
The ALMS API is an effort of the @lantis® Learning Community.
We believe we can build better communities through education and networking.
This API is an element in the ALMS Ecosystem.
ALMS was established to standardize and modernize training and education (Learning) management and delivery.
There is a growing realization of the benefits to gathering and storing information digitally.
In assessing the value of information there is a need to consider a wide range of formal and informal supporting documents, both on and offline. Those documents, more often than not, are scattered across a wide variety of sources.
Out of this perceived need – accumulating information from a wide variety of sources – the Atlantis Learning Community and the ALMS API were born.
ALMS API assumes that:
- There is a need to analyze information distributed across a wide variety of sources, platforms and technologies.
- Developing a commonly-accepted framework for gathering, storing and exchanging this information represents the best way of achieving this.
The goals of the ALMS API are:
- To make it easier to understand and compare information gathered from a wide variety of contexts, platforms and technologies.
- To maximize interoperability of services which create, gather, store and process information about information.
2.0 How to Use This Document
This is intended to be a Open-Source working document.
Whenever possible, the language and formatting used in this document is intended to be considerate of non-technical readers because various tools, systems and services are based on the specification set described below.
For this reason, sections that provide a high-level overview of a given facet of the ALMS API are labeled description or rationale. Items in this document labeled as requirements, details or examples are more technical.
This specification is split into three parts:
- Part one is this introduction. It offers some background, high-level summaries and direction on how to read the rest of the specification.
- Part two of this specification defines a data model for various data objects that are used in this specification.
- The most significant object within the ALMS API data model is the “Statement” object.
- This specification defines the properties of the Statement object
- Required Properties
- Noun – Person, Place, or Thing. Thing can be a .jpeg, .mp4, .txt, .doc, and all forms of raw bits.
- Verb – Action
- Creation Date
- History of transactions
- The rules of syntax for the values of those properties and how they are represented.
- This part helps to ensure that services implementing the specification follow a consistent data structure.
- Required Properties
- Part three of this specification sets out the transfer methods that must be used when communicating information.
- This includes the format of requests and the expected responses.
- Note that communication in ALMS API is not restricted to a “Learning Community Library (LCL)” “Learning Communities” communication only. LCLs can communicate with a wide range of “Authors” and a wide range of “Consumers.”
- ALMS API follows the guidelines of the REST software architecture style, (https://www.quora.com/topic/REST-software-architectural-style, https://en.wikipedia.org/wiki/Representational_state_transfer) and as such data is transferred via HTTP requests and responses.
- Part three also defines security methods allowing for the trusted exchange of information between the LCL and trusted “LCs”.
2.1 MUST / SHOULD / MAY
There are three levels of obligation with regards to conformance to the ALMS API specification identified by the terms MUST, SHOULD and MAY.
- A service or system that fails to implement a MUST (or a MUST NOT) requirement is non-conformant.
- Failing to meet a SHOULD requirement is not a violation of conformity, but goes against the recommendations of the specification.
- MAY indicates an option, to be decided by the developer with no consequences for conformity. Usage of these terms outside of requirement language does not designate a requirement and is avoided whenever possible.
- SHOULD NOT This phrase, or the phrase “NOT RECOMMENDED” mean that there may exist valid reasons in particular circumstances when the particular behavior is acceptable or even useful, but the full implications should be understood and the case carefully weighedbefore implementing any behavior described with this label.
Complete definitions of MUST, SHOULD, MAY, MUST NOT and SHOULD NOT are found in https://www.ietf.org/rfc/rfc2119.txt.
The use of an asterisk* following SHOULD indicates a very strong recommendation. It is planned that these recommendations will become MUST requirements in a future version. Not following these recommendations could risk interoperability and and/or lead to various other issues depending on the specifics of the recommendation.
These recommendations cannot be MUST requirements within this version as these would be breaking changes. The ALMS API Working Group strongly encourages adopters to implement these requirements as though they were MUST requirements, while continuing to support other adopters that might not do so.
2.2 Guidelines for Interpreting Descriptive Text and Tables
As a rule of thumb, if the guideline appears technical or seems to be a requirement, interpret it as such. This is especially true of longer, more, detailed explanations and of tables, each of which would be unintuitive and/or lengthy to dissect into a list of requirements.
Tables are used throughout this specification to define requirements for lists of properties, parameters, etc.
The tables define which properties are required, recommended and optional. Generally, the notion of “optional” relates to the service creating the object, while services receiving and interpreting the object need to be able to interpret all properties of that object. Often, properties are optional because the data may not be relevant in every context; if the data is relevant in a particular context, then it is expected the property will be populated.
If an optional property or parameter contains an object with properties that are recommended or required, then these properties are only recommended/required if the property or parameter containing them is used.
Examples are provided throughout the specification and in appendices to illustrate implementation. The content of these examples is fictional in order to illustrate the requirements of the specification and may not always illustrate the best practice approach to tracking the particular learning experience used in the example.
Examples can be used to inform interpretation of requirements, but are not intended to take precedence over requirements.
Where the specification does not include requirements relating to a particular facet of implementation, that detail can be considered to be outside of the scope of this specification. It is up to the implementer to determine a sensible approach. This specification tries to avoid vagueness and will usually give a rationale even if there no requirement in a given area.
The first element in the database is called the genesis block. The genesis block is hardcoded into the software and exists as an empty state, that is to say that it has no real value other than indicating the beginning. The genesis block may contain information about the rules or guidelines for the remaining database.
The genesis block is block zero, or the first block. After that, the database is formed by a series of blocks that link together to form a chain. This is where we get the naming of the blockchain technology.
The blocks in the chain each contain information or transactions. As you add transactions, this information is stacked in the block according to the time it was presented. The transactions contain anonymized information about who added or removed value in the transaction, as well as date and time. This combination of information and time creates a ledger documenting value or other resources in the database.
After the transactions have been stacked in the block, a signature or “hash” is added to the bottom of the block. The hash links to the previous block in the chain. These hashes form the links between the chains. The hashes link all of the way back to the genesis block.
The hash includes the number of the block, and the number of the next block in the chain. The hash also includes the date and time it was signed, as well as how many transactions are included in the block. The signature, or hash, shows up as a cryptographic, or encrypted hexadecimal key.
At this point, new blocks and transactions are added to the chain. Each block contains a series of transactions or comments. These transactions are followed by a hash in the block. As a reminder, each hash serves as a link to the other blocks in the chain, and indicates their order.
Serialization is the process of translating data objects and structures into a format for storage or transmission, such that the original data object can be recreated from the resulting serialization.
In some cases it might be possible to serialize a piece of data in more than one way. For example, a boolean property with a value corresponding to true might be represented as
1 depending on the serialization used.
ALMS API follows the rules of JSON for serializations (so boolean values are represented as
false). It might also be possible to represent the objects defined in this specification using other serializations, such as XML. This is out of scope of this specification and use of anything other than JSON to represent the objects defined in this specification is not conformant.
Even within the rules of JSON there are possible variations of how data can be serialized, especially in relation to data about time. This is significant as a number of features of ALMS API rely on systems being able to determine whether two Statements are equivalent. See Immutability and exceptions for more details about the properties of the Statement affected by this.
JSON allows for objects to have properties that contain empty objects. This is not recommended within ALMS API; if the Statement is not intended to contain data about a property then it is expected that the property will not be used at all. All required properties are required to contain values.
Activity (A): A type of Object making up the “this” in “I did this”; it is something with which an Author interacted. It can be a unit of instruction, experience, or performance that is to be tracked in meaningful combination with a Verb. Interpretation of Activity is broad, meaning that Activities can even be tangible objects such as a chair (real or virtual). In the Statement “Anna tried a cake recipe”, the recipe constitutes the Activity in terms of the ALMS API Statement. Other examples of Activities include a book, an e-learning course, a hike, or a meeting.
Activity Author (AA): The creator of the Packet.
ALMS API (ALMS API): The collection of rules articulated in this document which determines how learning experiences are defined, formatted, and exchanged so that independent software programs can exchange and make use of this information.
Application Programming Interface (API): A set of rules and standards created to allow access into a software application or tool. Authentication: The concept of verifying identity. Authentication allows interactions between two “trusted” parties.
Authorization (Au): The affordance of permissions based on role; the process of making one party “trusted” by another.
Avatar: The Public Persona used by the Learner or Learning Community.
Blockchain: The historical record of a particular Statement or Question
Client (C): Refers to any entity that might interact through requests. Some examples could be a Learning Community (LC), an Unregistered Consumer (UC), a Registered Consumer (RC), a Learning Community Library (LCL), or a Learning Management System (LMS).
Community of Practice (CoP): See Learning Community
Conclusion: A Statement that cannot be proved as it is a construct of an individual Learners experience. Conclusions can be reasonable or not-reasonable. Conclusions cannot be True or Not-true.
Endpoint (EP): An entry point in a service-oriented-architecture. ALMS API mirrors this approach with resources by defining the IRI from which communication takes place as an endpoint.
Fact (F): A Statement that can be directly observed.
Immutable: Adjective used to describe things which cannot be changed. With some exceptions, Statements in the ALMS API are immutable. This ensures that when Statements are shared between LCLs, multiple copies of the Statement remain the same.
Internationalized Resource Identifier (IRI): A unique identifier which could be an IRL. Used to identify an object such as a verb, activity or activity type. Unlike URIs, IRIs can contain some characters outside of the ASCII character set in order to support international languages. IRIs always include a scheme. This is not a requirement of this standard, but part of the definition of IRIs, per RFC 3987. What are sometimes called “relative IRIs” are not IRIs.
Internationalized Resource Locator (IRL): In the context of this document, an IRL is an IRI that when translated into a URI (per the IRI to URI rules), is a URL.
Inverse Functional Identifier: An identifier which is unique to a particular persona or Group.
Learner (L): An individual or group representation tracked using Statements performing an action within an Activity. Is the “I” in “I did this”.
Learning Community (LC): A group of practitioners connected by a common cause, role or purpose, which operates in a common modality. Learning Communities are focused on implementing ALMS API within a specific knowledge domain or use case. Individual LCs or Groups of LCs, can create domain-specific vocabularies, profiles, and curriculums. These practices usually involve work around defining use cases and curating the various vocabulary terms, synonyms, and other related metadata that might be preferred within a LC. They can also reuse existing vocabularies, profiles, and recipes already published by other LCs or participants of the ALMS API community.
Learning Community Library (LCL): A server (i.e. system capable of receiving and processing web requests) that is responsible for receiving, storing, and providing access to Learning Records.
Learning Experience: An event associated with learning. It is highly diverse as far as what it can be. Examples include reading a book, post, or watching a video, taking an online course, going on a field trip, engaging in self-directed research, or receiving a certificate for a completed course.
Learning Management System (LMS): “A software package used to administer one or more courses to one or more learners. An LMS is typically a web-based system that allows learners to authenticate themselves, register for courses, complete courses and take assessments” (Learning Systems Architecture Lab definition). An LMS in this document is used as an example of how a user is identified as “trusted” within a system and able to access its Learning Experiences.
Learning Record: An account of a learning experience that is formatted according to the rules of ALMS API. A Learning Record takes on many forms, including Statements, documents, and their parts. This definition is intended to be all-inclusive.
Learning Library Consumer (LLC): An ALMS API Client that accesses data from Learning Community Library(s) with the intent of processing the data, including interpretation, analysis, translation, dissemination, and aggregation.
Learning Record Provider (LRP): An ALMS API Client that sends data to Learning Community Library(s). Often, the Learning Record Provider will create Learning Records while monitoring a learner as a part of a Learning Experience.
Metadata Consumer: A person, organization, software program or other thing that seeks to determine the meaning represented by an IRI used within this specification and/or retrieves metadata about an IRI. An LCL might or might not be a metadata consumer.
Metadata Provider: A person, organization, software program or other thing that coins IRIs to be used within this specification and/or hosts metadata about an IRI.
Persona: A set of one or more representations which defines an Actor uniquely. Conceptually, this is like having a “home email” and a “work email”. Both are the same person, but have different data, associations, etc.
Profile: As much background as possible about the Author or Creator of the Statement.
Question: A information packet design to recieve a response Statement.
Recommended Action: A Statement that describes a action the Learner should take. For example: “Bring an umbrella.”
Representational State Transfer (REST): An architecture for designing networked web services. It relies on HTTP methods and uses current web best practices.
Service: A software component responsible for one or more aspects of the distributed learning process. An LMS typically combines many services to design a complete learning experience.
Statement: A single packet of bits. Follows the ALMS API data sctructure showing evidence for any sort of experience or event which is to be tracked in ALMS API as a Learning Record. A set of several Statements, each representing an event in time, might be used to track complete details about a learning experience.
Verb (V): Is the action being done by the Actor within the Activity within a Statement. A Verb represents the “did” in “I did this,” or “I found this.”
Vocabulary (V): A list or collection of the terms that are used by a LC for labeling or categorizing information in a particular domain. The use of a vocabulary ensures that everyone is using the same word to mean the same thing. This section explains and shows graphically how different pieces of xAPI can fit together.
5.0 Data Flow in ALMS API
Figure 1 – ALMS Algorithm
Figure 1 shows the information flow of learning experiences.
A learner either completes a learning experience, whereby they “Push” or “Add” that information to the LCL. Or they have a Question, whereby they “Pull” the answer to that question from the LCL.
This experience could take place in an online course, it could be on the job or it could be part of recreation. It really could be anything.
This experience could be tracked, on the learner’s behalf, by a trusted Learning Community (LC). The LC can also be responsible for the trusted relationship between the experience and the learner. This might even include launching content for the learner and managing digital rights associated with the content.
The LC creates Learning Records and sends them to one or more Learning Community Libraries (LCLs). The LCL stores the Learning Records and makes them available to any authorized Client. A Learning Record Consumer (LRC) is a type of Client that accesses Learning Records and makes use of them.
6.0 Agent and Persona Management
ALMS API Agent and Persona Management
ALMS API grants the framework for allowing selective access to one’s personal data.
This is done through the management of what are called personas. In ALMS API, each persona represents the “I” in “I did this” and is logically the subject of the Statement. Each Agent or Group in ALMS API corresponds to a persona.
A learner sending Learning Records to an LRS could have multiple personas (Agents) associated with him or her. In Figure above a learner accesses multiple services. Some of these services are used at work, others at home. Some are used for social purposes and others are used for educational or professional puproses. Thus, there are multiple personas functioning collectively within these services.
Each of these services send data to the LCL. Afterwards, there are Statements from three different personas of the same learner. The LCL can aggregate all of the information of each of the personas into one “Person” Object. This object can be retrieved from The LCL via the Agents Resource.
How the LCL knows that these multiple personas belong to a single person is out of scope of this specification and there are several different approaches that an LCL can take. It’s also possible that some LCLs will have no mechanism for associating personas.
7.0 Extending xAPI
ALMS API can be extended in a few ways. The most notable are Statement extensions, which allow great flexibility within Statements. It is recommended that LCs agree on how to use extensions for their particular use cases and use profiles whenever possible.
Implementation details are covered in 4.1 Extensions. The About Resource is another instance where ALMS API supports extensions.
The LCL may find it useful to communicate features or behaviors beyond this specification. The LCL can use extensions to the About Resource to facilitate this communication.
8.0 Profiles, Vocabularies, and Learning Communities
ALMS API strictly defines the structure of Statements, but is very flexible as to the contents of that structure.
For example, the specification requires that all Statements have a “verb” property, but does not restrict the values of that property; any Verb can be used. This flexibility enables ALMS API to be used in any context, including future use cases not envisaged by the specification authors.
It is intended that LCs will define Verbs, Activity types, contextual relationships, extensions, etc. to be used in their profiles by providing unique identifiers wherever applicable.
The CoP will define these identifiers and their metadata in a Vocabulary. A profile is a set of rules and vocabularies to implemented in addition to xAPI for the particular use case being addressed. It is very important that such communities exist and share best practices. For more information on publishing vocabularies, see the Vocabulary Companion Specification and Vocabulary Primer documents.
It is recommended that a profile use a unique “category” within a Statement’s context to refer to any Statement which implements the profile. An example of a LC for the medical field is the MedBiquitous Learning Experience Working Group.
- Discussion Structure
- Creation Date
- Is it Original Content
- Taxonomy – (Describes how the discussions are “Connected.” The organizational structure of the information.)