As Engine continues to evolve and introduce new and refined features, older ones do sometimes get removed. As of Engine 22, all support for the V1 API has been removed. Consequently, you will need to convert any V1 requests to use V2, but rest assured, we're here to help make the transition as painless as possible!
First off, click here to view a complete list of V2 API endpoints. The first thing you may notice is the drastic increase in available resources, as V2 offers a ton more options and flexibility than its predecessor. Whatever functionality you were using in V1 is almost certainly available - with only a few exceptions - in V2. However, there are a few things to be aware of before getting started with this transition.
Specifying the Tenant Name
The way to specify the tenant name in an API request has changed from V1 to V2. V1 endpoints had this pattern:
{EngineRoot}/api/v1/{tenant}/{resource}
For example, to get a list of courses from the "default" tenant in V1, one would make a GET request to a URL that looks like this:
http://MyHost/RusticiEngine/api/v1/default/courses
In V2, one does not specify the tenant name in the URL. To convert the above endpoint to V2, first increment the base URL from "v1" to "v2". Then, remove the "default" tenant name section from the path. Instead, to specify which tenant the request is for, add a request header called "EngineTenantName" and set its value to the tenant name. The end result is a pattern that looks like this:
{EngineRoot}/api/v2/{resource}
And the converted "GetCourses" endpoint looks like this:
http://MyHost/RusticiEngine/api/v2/courses
To further compare and contrast the difference between these two requests, you can view the documentation for this resource in both V1 and V2 formats.
Creating Tenants
Engine's architecture is tied to the concept of "tenancy", and every Engine installation begins with one tenant called "default". For some customers, this is sufficient, and they never create additional tenants beyond the starting "default". However, many customers do require the ability to partition and serve distinct groups or applications, and they create new tenants to serve this purpose.
A discussed above, in V1, tenant names are part of the URL. During any V1 API request processing, if Engine ever encountered a tenant that didn't already exist in its database, it would automatically (and silently) create that tenant in its database. For example, perhaps you make a GET request to V1's /{tenant}/about endpoint, and the URL looks like this:
http://MyHost/RusticiEngine/api/v1/fee-fi-fo-fum/courses
From that moment on, your Engine database would have a tenant called "fee-fi-fo-fum", and you could import courses and launch registrations against it.
The V2 API no longer functions like this, and Engine will not automatically create tenants under any circumstance. Instead, to create a new tenant, you must explicitly do so by making a PUT request to the CreateOrUpdateTenant endpoint.
If you make a V2 API request and specify "banana-rama" for the "EngineTenantName" request header before having called into CreateOrUpdateTenant to create the tenant, Engine will respond with a "400 Bad Request" error and this message:
{
"message": "'banana-rama' is not a valid tenant name"
}
Postback and Schema Format
The JSON format for automatic registration and import results postbacks changed from V1 to V2. Those using the V1 API on Engine 2018 and above may have set Engine's ApiPostbackDataModelVersion setting to "v1" to continue receiving the older format. However, this will no longer work, and the setting no longer exists in Engine.
If you deserialize the postback JSON into Engine's model classes, update those dependencies to those from the V2 client library. And if you're parsing through the JSON yourself, you must update your code to account for the format differences. To view V2's "registrationSchema" and "importJobResultSchema" models, see the documentation for the GetRegistrationProgress and GetImportJobStatus endpoints, as they return the same JSON as the automatic postbacks.
If your application does not consume automatic postbacks from Engine, you're likely using V1's /{tenant}/registrations/{registrationId}/progress and /{tenant}/courses/importJobs/{importJobId} endpoints to track registrations and import results. The same considerations apply when switching to their respective V2 equivalents, GetRegistrationProgress and GetImportJobStatus.
Keep in mind that Engine 22 introduced a revamped webhook system. Both ApiRollupRegistrationPostbackUrl and ApiImportResultsPostbackUrl are still in place, and you can continue using them to configure postbacks URLs. However, we will remove these older postback mechanisms in a future major Engine release.
V1 API 'configuration' Parameter
Customers that started on versions that predate the V1 API integrated with Engine by subclassing special integration classes and calling public methods on Engine's internal libraries (e.g., using ScormEngineManager to import courses). If this doesn't sound like your application or Rustici Software hosts your Engine application, then the following information doesn't apply to you. In other words, this section is for those who do not interface with Engine exclusively through its REST API.
To accommodate the use of both the integration code layer and the V1 API, many of the V1 API endpoints take an optional "configuration" parameter. This parameter is for setting values on custom variables that are then accessed in overridden Engine methods. The V2 API does not support the "configuration" parameter. This omission is part of a larger road map that eventually results in dropping support for integration code layers altogether. Oftentimes, replacing the logic around custom variables is a simple matter of migrating code logic from the integration layer into your own application. However, sometimes a viable solution isn't as obvious. In those cases, you will need to work with our support staff during the upgrade project or contact us at support@rusticisoftware.com.