How To Use API Consumer

How to Make an API Request

Only Lab Profiles with a development status of Complete are consumable via API.

• Requests are not case sensitive. Requests can use either GET or Post.

  • GET: used to request data from a specified resource.

  • POST: used to send data to a server to create/update a resource.

API Request Format

API requests use Methods and Parameters in the URL.

A typical API request would look like:

https://labondemand.com/api/v3/[method]?[parameters]

A request to launch a lab will look like:

https://labondemand.com/api/v3/launch?labid=100&userid=555&firstname=Joe&lastname=Smith&email=joe.smith@email.com

launch is the method.

labid, userid, firstname, lastname and email are the >parameters.

• labid: this is the lab ID of the lab that is to be launched. The ID can be >found in the URL while viewing the lab profile in Skillable Studio.

• userid: the user ID you use to identify the user in your external system.

• firstname: the first name of the user that the lab launch will be associated with.

• lastname: the last name of the user that the lab launch will be associated with.

• email: the email address on the user profile of the user that the lab launch will be associated with.

API Testing Tools

If you want to test your API requests before implementing them, you can do so using an API testing tool. There are many tools available for testing an API request. One of the most common tool used is Postman, and is available on Windows, macOS and Linux (x32/x64).

You may download a Postman Collection (2.1) of calls here. Be sure to edit the authorization header.

In this guide, we will walk through the steps to use the Launch APi request, to launch a specified lab for a specified user.

To launch a lab via an API request in Postman:

1. Download Postman.

2. Launch the installer and install Postman.

3. Open Postman.

4. Select the + (plus) icon in postman to create a new request.

   

5. Select Request in the dialog that pops up.

6. Ensure that GET is selected.

   

7. Copy the example API request below from the Launch API request documentation:

   • https://labondemand.com/api/v3/launch?labid=100&userid=555&firstname=Joe&lastname=Smith&email=joe.smith@email.com

8. Paste the URL into Postman.

   

9. You'll see that Postman parses the URL and displays query parameters in the appropriate field in the Value column.

   

10. Replace the text in the value column, with data that corresponds to the key column. I.E. replace 100 with the lab ID of the lab that is to be launched.

    

11. Next, Headers need to be configured with the API key, to authenticate and use the API consumer. The API key is found in Skillable Studio, or it can be obtained from your organization.

    

12. Select Show and copy the API key.

13. In Postman, select the Headers tab.

    

14. Enter the API Key in the Value Column.

15. Enter api_key in the key column.

    

16. The API request now has all required information to successfully launch a lab. Select Send to submit the API request.

    

17. The lab will now launch for the specified user. Postman will return a JSON response with information about the result of the API request. The information in the response corresponds with the information on the Launch API details documentation.

    

    • Result: 1 = success.

    • URL: the URL to the lab instance.

    • LabInstanceID: 148562 = the lab instance ID.

    • Expires: when the lab will expire (in Unix epoch time).

    • ExpiresTime: when the lab will expire (in Unix epoch time).

    • EstimatedReadySeconds: the estimated amount of seconds it will take for the lab to be ready for use.

    • Error: in the event of an error, this will contain a detailed error message.

    • Status: 1 = success.

API Consumer Best Practices

API Workflow

As a best practice the API key should never be exposed to client-side code. Below is a sample workflow for using and integrating API calls. The sample assumes that the client side has a button or page that the student selects to launch a lab via API.

1. Student selects a button that initiates the API call.

2. An ajax call is made to the customer-owned service or learning management system.

3. The customer-owned service makes a Launch API call and receives the lab URL from Skillable Studio.

4. The ajax call returns to the browser and includes the lab URL.

5. Client-side code redirects to the URL or spawns a new window and directs the new window at the lab URL.

Spawning a new window is preferred for the following reasons:

• It allows for the browser window to be resized to the ideal size for the student's machine. Resizing can't be done in a redirect, as browser's do not allow resizing of user-opened windows.

• The student is able to maintain the page they launched the lab from. It is best practice to launch the lab in its own window, so the student can navigate to the page the lab was launched from if needed.

Do not use Strict Mapping

We advise against using strict mapping of API objects. We will add new API objects, but we will not remove any API objects that are already in place. If API objects are strictly mapped, your API integration may not work properly when new API objects are added.

Window Manipulation

If you launch a lab in a new window using JavaScript, Skillable Studio will resize the lab window after it is launched.

To launch a lab in a new window, use the following JavaScript:

window.open(labUrl, "lab", "width=800,height=600,status=0,resizable=1,toolbar=0,menubar=0,location=0,scrollbars=0");

This tells the browser to open a new window with dimensions of 800x600. After a new window is opened, Skillable Studio will resize the window appropriately for the lab type that is being launched (Virtualization or Cloud Slice). Since the initial window dimensions were set by a script, future scripts are permitted to change those dimensions (resize the window).

Windows spawned in any other context are only resizable by the user. If you open the window using an HTML link, or simply redirect the current window to the lab URL, Skillable Studio will be prevented from resizing the window.

• Cloud Slice labs consist of two windows; the resource portal and lab console.

• Virtualization based labs consist of one window; the virtual machine and the lab console.

  • Lab console: on the right side of the screen, housing the instructions and any lab resources.

  • Resource portal: on the left side of the screen, housing the cloud platform or the virtual machine(s) that the lab utilizes.