ztC Edge systems support the Representational State Transfer (REST) application programming interface (API). With access to the REST API methods, you can collect system information, including physical machine (PM) and virtual machine (VM) properties, statistics, and alerts. You can also execute some administrative tasks including creating VMs, powering VMs on and off, putting a PM into maintenance mode, and powering the system off. You can use these HTTP methods to create your own customized Web-based applications to monitor and manage the ztC Edge system.

The system provides the REST API and interactive REST API documentation through the OpenAPI (also known as Swagger™) Specification. You can access the documentation directly from the local ztC Edge system.

To begin exploring the REST API on ztC Edge systems, see the following sections:

• Accessing the REST API documentation

• Logging In for REST API Testing

• Extending a Login Session with the Refresh Token

• Logging Out of the REST API

• List of REST API Methods

Accessing the REST API documentation

In a web browser, open the following URL, which includes the hostname or IP address of your ztC Edge system:

The documentation describes the API methods and syntax, and also allows you to try the methods on your own system.

Logging In for REST API Testing

1. Open the REST API documentation page.

2. Under Authentication API, click the /v2/login method to expand it, and click Try it out.

3. The system displays the syntax for the REST API /v2/login method. Under Request Body, update the text to enter the username and password for a user account on the ztC Edge system:

   {
   "username": "type_username_here",
   "password": "type_password_here"
   }

   Log in to an account that has the appropriate level of privileges for the REST API methods that you want to use.

4. Below the Request Body, click Execute and view the Server Response. If the method is successful, the response contains two REST API session authentication tokens (token and refreshToken). If the method is unsuccessful, the response might contain a message similar to Unauthorized - Invalid username/password.

5. Upon a successful login, copy the authorization token string to your management PC running the ztC Edge Console. Copy only the text between quotes to the clipboard to use in a subsequent step.

   {
   "token":
   "eyJhbGciOiJIUzUxMiJ9dgkl;jageXNUaW1lTWlsbGkiOjE2OTQzMjUzNTgwODMkilegjk",
   "refreshToken":
   "eyJhbGciOiJIUzUxMiJ9.eyJzeXNUaW1lTWlsbGkiOjE2OTkyMzQ2NDI4MTksInN1YiI6I"
   }

6. At the top of the REST API documentation page, on the right side, click Authorize.

7. Under bearerAuth, in the Value field, paste the authorization token string, and then click Authorize. If your login is successful, the dialog box displays a Logout button.

8. Click Close or X to close the dialog box and return to the REST API documentation page.

9. Proceed with your REST API testing.

Extending a Login Session with the Refresh Token

After logging in as described in Logging In for REST API Testing, the login session remains active for 45 minutes. To extend the login session, use the /v2/refreshToken method to reset the session timeout to 90 minutes.

1. From the original /v2/login response of your current login session, copy the refreshToken string to your clipboard. Copy only the text between quotes.

   {
   "token":
   "eyJhbGciOiJIUzUxMiJ9dgkl;jageXNUaW1lTWlsbGkiOjE2OTQzMjUzNTgwODMkilegjk",
   "refreshToken":
   "eyJhbGciOiJIUzUxMiJ9.eyJzeXNUaW1lTWlsbGkiOjE2OTkyMzQ2NDI4MTksInN1YiI6I"
   }

2. Under Authentication API, click the /v2/refreshToken method to expand it, and click Try it out.

3. The system displays the syntax for the REST API /v2/refreshToken method. Replace the string text between the quote marks with the refreshToken string you copied in the previous step:

   {
   "refreshToken": "string"
   }

4. Below the Request Body, click Execute and view the Server Response.

5. From the response of the /v2/refreshToken method, copy the new authorization token string to your clipboard. Copy only the text between quotes.

   {
   "token":
   "eyJhbGciOiJIUzUxMiJ9.eyJzeXNUaW1lTWlsbGkiOjE2OTkyMzQ2NDI4MTksInN1Yi",
   }

6. At the top of the REST API documentation page, on the right side, click Authorize, and then click Logout.

7. Under bearerAuth, in the Value field, paste the new authorization token string, and then click Authorize. If your login is successful, the dialog box displays a Logout button.

8. Click Close or X to close the dialog box and return to the REST API documentation page.

9. Proceed with your REST API testing.

Logging Out of the REST API

At the top of the REST API documentation page, click Authorize and then click Logout.

List of REST API Methods

The following methods are available: