---
title: "How To Use API Consumer"
slug: "how-to-use-api-consumer"
tags: ["lgc"]
updated: 2024-09-11T20:46:06Z
published: 2024-09-11T20:46:06Z
canonical: "docs.skillable.com/how-to-use-api-consumer"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.skillable.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.](https://raw.githubusercontent.com/LearnOnDemandSystems/ConnectAPI/main/Skillable-lab-OpenAPI.yaml) 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](https://www.getpostman.com/downloads/).
2. **Launch the installer** and install Postman.
3. **Open** Postman.
4. Select the **+ (plus) icon** in postman to create a new request.

![Postman Plus Icon](https://cdn.document360.io/a298db04-a0fe-47e0-bfe3-c52d6f9d7c8c/Images/Documentation/postman-new-button.png)
5. Select **Request** in the dialog that pops up.
6. Ensure that **GET** is selected.

![Postman GET tab](https://cdn.document360.io/a298db04-a0fe-47e0-bfe3-c52d6f9d7c8c/Images/Documentation/get-selected.png)
7. Copy the example API request below from the [Launch API request documentation](https://docs.skillable.com/apidocs/launch-a-lab-1):
  - `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.

![Postman URL](https://cdn.document360.io/a298db04-a0fe-47e0-bfe3-c52d6f9d7c8c/Images/Documentation/enter-request-url-postman.png)
9. You'll see that Postman parses the URL and displays query parameters in the appropriate field in the **Value** column.

![Postman Query Params Value Column](https://cdn.document360.io/a298db04-a0fe-47e0-bfe3-c52d6f9d7c8c/Images/Documentation/query-params.png)
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.

![Postman Query Params Value Column](https://cdn.document360.io/a298db04-a0fe-47e0-bfe3-c52d6f9d7c8c/Images/Documentation/completed-replaced-date-postman.png)
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.

![API Secret Key](https://cdn.document360.io/a298db04-a0fe-47e0-bfe3-c52d6f9d7c8c/Images/Documentation/api-key-in-lod.png)
12. Select **Show** and copy the API key.
13. In Postman, select the **Headers** tab.

![Postman Headers tab](https://cdn.document360.io/a298db04-a0fe-47e0-bfe3-c52d6f9d7c8c/Images/Documentation/headers-tab.png)
14. Enter the **API Key** in the **Value** Column.
15. Enter `api_key` in the **key** column.

![Postman Headers tab API key](https://cdn.document360.io/a298db04-a0fe-47e0-bfe3-c52d6f9d7c8c/Images/Documentation/api-key-entered-in-postman.png)
16. The API request now has all required information to successfully launch a lab. Select **Send** to submit the API request.

![Send button](https://cdn.document360.io/a298db04-a0fe-47e0-bfe3-c52d6f9d7c8c/Images/Documentation/send-button.png)
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.

![JSON Response](https://cdn.document360.io/a298db04-a0fe-47e0-bfe3-c52d6f9d7c8c/Images/Documentation/api-json-response.png)
  - **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.

Labs in Skillable Studio are housed in a Lab Profile. The Lab Profile contains the information about the configurable settings and the virtual machines that make up a lab. For a Lab Profile to be published it must be part of a Lab Series.

An API, also known as an Application Programming interface, consists of a defined set of rules and protocols that enable seamless communication between different software applications. A common language for software systems to collaborate effectively.