Good news fellow SCORMarians. We are excited to announce the beta release of our SCORM Cloud’s API v2. After 10 years of delivering millions of registrations to learners across the world, it was time to refresh the programmable interface so many of our customers use to integrate with SCORM Cloud. The v2 API is primarily a modern REST interface to our existing functionality with a few nuanced changes in API behavior that we’ll review in more detail later on. The initial beta release of the v2 API only supports working with courses and registrations, but functionality for dispatches, invitations, and xAPI will be added quite soon.
Before getting into the nitty gritty of what has changed, we’ll share with you a bit of history about SCORM Cloud. 10 years ago, which is a very long time in software, we modeled and launched our API after Flickr. It was “REST-like” at best as it was created before REST became well established. While the API service structure was novel at the time, it has become dated and past the point of sustainability. The v1 API isn’t really broken so we aren’t throwing the baby out with the bath water. We will still maintain support and bug fixes for the v1 API, but we won’t be adding any new functionality to v1. Sometime down the road after v2 usage surpasses v1 usage, we’ll announce sunset dates for the v1 API.
Differences in the v2 API
Even though the interface for the v2 API is completely different than the v1 API, very little has actually changed regarding the functionality of what is offered by SCORM Cloud. We actually maintain the same implementation on the backend for both versions of the API. We have removed some unwanted functionality in the transition from v1 to v2, and over time the v2 API will diverge in functionality from the v1 API as more methods are added to the v2 API. Below are some of the key differences between the two versions.
Data Format
While the v1 API has limited support for JSON, XML is the primary payload format. The v2 API solely supports JSON, which provides more compact payloads that are easily consumed in javascript and other languages.
Authentication
Authentication in the v1 API is limited to basic auth using a shared secret and key. The v2 API will support both basic auth and OAuth 2.0 with an implicit grant authentication flow. This will allow our customers to securely interact with the v2 API within a SPA or other browser based scenarios.
Course Imports
The v1 API supports both synchronous and asynchronous imports. Synchronous imports are easier for customers to implement on the frontend, but they become problematic once the course being imported exceeds the size that can be processed in under 30 seconds. At that point, asynchronous imports are required to avoid gateway timeouts. We have seen a pattern of customers using synchronous imports because the initial development time was shorter, and then finding themselves in a rush to rewrite their integration to support asynchronous imports because they need to upload courses much larger than their initial testing required. Since the v2 API does not support synchronous imports, future customers will avoid this pitfall from the onset.
Tagging
Tagging still exists in the v2 API. However, it is no longer it’s own service. Rather than having a tag endpoint or service that lives outside of courses, registrations, and learners, we’ve embedded the relative tagging methods in each of those respective endpoints. We have also removed the ability to tag registrations and learners at launch. While this was a convenience in the v1 API, it was in conflict with the REST model of the v2 API.
Getting started with the v2 API
If you are an existing customer, the best way to get started with the v2 API is to create a new application in SCORM Cloud and then head over to our docs page to find API clients and detailed walkthroughs of how to get started. You will probably find that v2 API feels really familiar as it just has a more modern client code to work with.
We developed the v2 API using Swagger, which means developers can integrate against the v2 API using common rest clients or generate a client for the language of their choice using well established Swagger tools. We have generated clients in Java, .NET, and PHP for our initial release and will follow up with Python, Ruby, and other languages based on demand. Because of the popularity and success of swagger and the OpenAPI specification, we believe the v2 implementation will remain palatable to developers for another decade.
All new applications are v2 enabled, but during our initial rollout we will require customers to explicitly enable v2 functionality to existing applications within SCORM Cloud. This is in large part because we have some data migration jobs that move existing package properties into API configuration settings in the background when the v2 API is enabled for an existing application. This manual step will not be required for long. In the coming months we will enable the v2 API for all existing applications, without requiring any action from our customers. All of the v1 functionality will of course continue to work for both existing and new applications.
