API Clients

Engine has a fairly extensive API, with many endpoints and schemas. The good thing is that most applications only make use of a relateively small handful of these enpdoints. Which means that writing your own code to make the necessary HTTP requests to the API is not a huge undertaking.

However, it can be much simpler and faster to use a generated client library for the API. These libraries can simplify working with the schemas required for requests and response.

.NET and Java Clients

If you are hosting an on-premise installation of Engine, your Engine distribution zip will contain an ApiClient folder. In it, you will find the generated library that allows native access to the Engine API, as well as any dependencies it requires.

The .NET library to include is called RusticiSoftware.Core.api.client.v2.dll. Load the Object Browser in Visual Studio for a solution that includes the API client library.

The Java library is named RusticiSoftware.Core.api.client.v2.jar.

For our Managed Hosting customers, just reach out to us and we can provide a generated library for the .NET Framework or Java. We do not currently host our libraries on any public package manager sites (eg, Nuget or Maven).

All Other Languages

For languages beyond .NET Framework and Java, you will have to generate your own library. Thankfully, that is a pretty straightforward process due to our use of Swagger to define our API.

We use (and so can you) a tool called Swagger Codegen to take the yaml file defininig the API and generate the appropriate language library from it.

The repo linked above should have all the info you need. After downloading the swagger-codegen-cli.jar from the repo, the command you can use to generate the client is something like:

java -jar swagger-codegen-cli.jar generate -i path/to/v2.yaml -l <language> -o /output/directory/

The yaml file that defines the V2 API is located in your Engine installation at the path <yourdomain>/RusticiEngine/defaultui/admin/static/v2.yaml. You can download it from there in order to give the generator access to it.

Note: There are some other Swagger code generator tools out there, so if the one above doesn't have the language you need, a quick Google search may lead you to an alternative!

Examples

Default Imports

These are the packages you'd need to import for the sample code.

import RusticiSoftware.Core.api.client.*;
import RusticiSoftware.Core.api.client.v2.*;
import RusticiSoftware.Core.api.client.v2.Models.*;

Default Using Statements

These are the namespaces you'd need to import to use the sample code.

using RusticiSoftware.Core.api.client.v2.Api;
using RusticiSoftware.Core.api.client.v2.Client;
using RusticiSoftware.Core.api.client.v2.Model;

Basic Client Configuration

This just sets up the default basis for your client calls with the endpoint and basic auth credentials. We'll use this in all the other calls.

// We use the default tenant created when you install Engine
string tenantName = "default";

ApiClient defaultClient = new ApiClient();
defaultClient.setBasePath("http://localhost:8080/RusticiEngine/api/v2");
defaultClient.setUsername("apiuser");
defaultClient.setPassword("password");

// This sets the default client so that you don't have to pass these values to all the
// other clients objects.
Configuration.setDefaultApiClient(defaultClient);

// We use the default tenant created when you install Engine
string tenantName = "default";

// This sets the default values globally so you don't have to set them on each
// client object directly.
Configuration.Default.BasePath = "http://localhost/RusticiEngine/api/v2";
Configuration.Default.Username = "apiuser";
Configuration.Default.Password = "password";

Advanced Client Configuration

In addition to the options laid out above, there are a few other options you have for configuring the default behavior of your API client. Below is an example of the most common configurations available, but please feel free to explore the defaultClientConfiguration.Default class for other options.

// Here, you can specify custom header values, if needed
defaultClient.addDefaultHeader("X-My-Header", "MyValue");

// Default connection timeout, in milliseconds.
defaultClient.setConnectTimeout(30000);

// Here, you can specify custom header values, if needed
Configuration.Default.AddDefaultHeader("X-My-Header", "MyValue");

// Default connection timeout, in milliseconds. Default is 10 seconds
Configuration.Default.Timeout = 30000;

Import a Course

This sample shows us import a course by telling Engine to fetch the zip package from a URL.

String courseUrl = "http://yourdomain.com/courses/RuntimeBasicCalls_SCORM12.zip";
String courseId = UUID.randomUUID().toString();
Boolean allowCreateNewVersion = false;

ImportFetchRequestSchema fetchRequest = new ImportFetchRequestSchema();
fetchRequest.setUrl(courseUrl);

CourseApi courseApi = new CourseApi(defaultClient);
String importJobId = courseApi.createFetchAndImportCourseJob(tenantName, courseId, fetchRequest, allowCreateNewVersion).getResult();

// Now we can either loop and wait for the job to finish before continuing (like below), or you could use the ApiImportResultsPostBackUrl
// setting to configure a web hook for Engine to post to when it's done.

ImportJobResultSchema jobResult = courseApi.getImportJobStatus(tenantName, importJobId);

while (jobResult.getStatus() == ImportJobResultSchema.StatusEnum.RUNNING) {
    jobResult = courseApi.getImportJobStatus(tenantName, importJobId);
}

// At this point, the status will either by COMPLETE or ERROR, and you would act accordingly

string courseUrl = "http://yourdomain.com/courses/RuntimeBasicCalls_SCORM12.zip";
string courseId = Guid.NewGuid().ToString();
bool allowCreateNewVersion = false;

ImportFetchRequestSchema fetchRequest = new ImportFetchRequestSchema(courseUrl);

CourseApi courseApi = new CourseApi();
string importJobId = courseApi.CreateFetchAndImportCourseJob(tenantName, courseId, fetchRequest, allowCreateNewVersion).Result;

ImportJobResultSchema jobResult = courseApi.GetImportJobStatus(tenantName, importJobId);

// Now we can either loop and wait for the job to finish before continuing (like below), or you could use the ApiImportResultsPostBackUrl
// setting to configure a web hook for Engine to post to when it's done.

while (jobResult.Status == ImportJobResultSchema.StatusEnum.RUNNING)
{
    jobResult = courseApi.GetImportJobStatus(tenantName, importJobId);
}

// At this point, the status will either by COMPLETE or ERROR, and you would act accordingly

Create a Registration

This creates a registration for the course we imported above.

String regId = UUID.randomUUID().toString();

LearnerSchema learner = new LearnerSchema();
learner.setId("test.user@example.org");
learner.setFirstName("First");
learner.setLastName("Last");

CreateRegistrationSchema registration = new CreateRegistrationSchema();
registration.setCourseId(courseId);
registration.setLearner(learner);
registration.setRegistrationId(regId);

RegistrationApi regApi = new RegistrationApi(defaultClient);

// You should usually pass null for the last parameter (courseVersion) so that we'll
// use the latest version of the course
regApi.createRegistration(tenantName, registration, null);

string regId = Guid.NewGuid().ToString();

LearnerSchema learner = new LearnerSchema("myLearnerId123", "FirstName", "LastName);

// There are a lot of optional properties in the schema that you often won't pass, but are available
// to set in the constructor or as properties on the registration object.
CreateRegistrationSchema registration = new CreateRegistrationSchema(courseId, learner, regId);

RegistrationApi regApi = new RegistrationApi();

// You should usually pass null for the last parameter (courseVersion) so that we'll
// use the latest version of the course
regApi.CreateRegistration(tenantName, registration, null);

Get the Launch URL

This gets the URL you'd use to launch this particular registration we just created.

LaunchLinkRequestSchema launchRequest = new LaunchLinkRequestSchema();

// We're not setting any optional properties, so our launchRequest object doesn't get anything set
String launchUrl = regApi.buildRegistrationLaunchLink(tenantName, regId, launchRequest).getLaunchLink();

LaunchLinkRequestSchema launchRequest = new LaunchLinkRequestSchema();

// We're not setting any optional properties, so our launchRequest object doesn't get anything set
string launchUrl = regApi.BuildRegistrationLaunchLink(tenantName, regId, launchRequest).LaunchLink;

results matching ""

    No results matching ""