Using the RESTFul API

This RESTful API is for use with your Landslide Performance Test System. This is a licensed product.

Introduction

Landslide provides direct, but limited, access to the TAS organized around REST. This makes automation functionality readily available to a wide variety of clients via HTTP/S, allowing the use of existing tools, available for many languages and environments, to create Spirent Landslide Automation clients. Automation clients no longer require a Spirent Landslide installation on the client system.

The HTTP request methods GET, POST, and DELETE are used with a URI identifying a resource or function to provide access to all Spirent Landslide RESTful functionality. The RESTful functionality covers the major operations to provision test servers and to start and command test sessions. Some modification of test sessions and related objects is supported. The HTTP PUT, MOVE, COPY, PATCH, HEAD, and PROPFIND methods are not supported.

NOTE:

Each URL begins with: http://tas-ip-address:8080/api/...where the tas-ip-address specifies the Landslide Manager server to connect to, 8080 identifies the port that the API is served from, and the “api” portion identifies the service, and following that are the resources to access.
For HTTPS the port must be 8181 https://tas-ip-address:8181/api/.. and you must accept the Self-Signed Certificate, via a browser exception or your automation's truststore, and optionally fully install our self-signed SSL Certificate. The Certificate will change with each TAS Release/Upgrade.
Added support for Swagger UI - Landslide Home Page TAS Manager API.

Demo Page 1- Admin Queries

List Running Tests - View a list of all running test sessions (including recently completed ones)

Cleanup Completed Tests - Delete all completed test sessions started via RESTful API

List Test Servers - View listing of all test servers

Demo Page 2- Run Test Session

To run a test via the test page, first save your test in the Global Library or a Custom Library where you can determine the Library Id.
The Global Library = 0, Custom Library Ids are listed on the Custom Library Admin Page.
The continue button will become available with an Automation Control Wait Step.
Overall Pass/Fail Status will be shown if using Pass/Fail Criteria. When the test completes, links to result files will be shown.
Delete Completed test sessions to release the TAS Resources.

URI Structure

For a comparison of curl, raw HTTP and Python, refer to Comparison of REST Request Example Formats.

In the example URLs, a trailing slash “/” is used to denote container type resources (lists/collections of items). Individual resources will not be followed by a slash. For example, when getting a list of all test servers, the “testservers/” container is specified:

GET http://tas-ip-address:8080/api/testservers/

When getting information about a specific test server, the test server id resource is specified:

GET http://tas-ip-address:8080/api/testservers/8

This convention for containers and items is similar to directories and files, where containers (directories) are denoted by a trailing slash, and items (files) are not.

In most cases, URIs and URL Query Arguments are case-insensitive. One exception is when they identify a specific named object. For example, /api/runningTests/ and api/RUNniNGtests/ will both work. But /api/RunNiNGtests/1/measurements/?tab=NaME will not work unless the tab name is exactly “NaME”

Authentication

The Landslide RESTful API uses HTTP Basic Authentication, expecting the Authorization header field with BASE64 encoded username and password in all HTTP Requests.

Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

References:

https://tools.ietf.org/html/rfc2617#page-5

https://en.wikipedia.org/wiki/Basic_access_authentication

The API accepts request from any IP Address, via Access-Control-Allow-Origin: * header. And also support the OPTIONS HTTP Request Method. These allow standard JQuery AJAX requests to be made from any location.

References:

https://en.wikipedia.org/wiki/Cross-origin_resource_sharing

Persistent Connections

The Landslide RESTful API uses a persistent connection by default. For successfully authenticated clients, the TAS will keep the socket open until the client closes it. Using the standard “Connection: close” HTTP header, the client can request that the TAS close the connection after the first response. If the client does not have access to the standard HTTP header, the user can add an “X-LS-REST-Connection: close” header. The custom header will take precedence over the standard header. Users should be aware of how many connections their REST clients are using. If a client creates a new connection for each request and does not properly close the connection, eventually all 48 simultaneous user-connections allowed will be used up.

For any client using Persistent Connection, at least one request must be made every 15 minutes or else the connection will be assumed abandoned and closed after 15 to 25 minutes. The TAS only checks the connections every 10 minutes, hence the range of 15 to 25m. If the connection is established in between two 10m TAS checks, the connection won’t be determined to be over-time until the 3rd TAS check.

Also, if the first message sent to the TAS by a client connection takes longer than 10s to starting reading by the TAS, that connection will be closed. This timer is configurable via TAS-Setting “client_read_timeout_s”. See topic - Edit Settings

Examples:
Connection: close

X-LS-REST-Connection: close

References:
https://en.wikipedia.org/wiki/HTTP_persistent_connection

Error Codes and Responses

HTTP Status Codes

Standard HTTP status codes are used to indicate the success or failure of every API request. Error codes in the 2xx indicate success, codes in the 4xx range indicate an error with the data provided to the API or with the use of the API, and codes in the 5xx range indicate a server-side error.

Error Responses

When the Landslide REST API returns an error response, the response body is JSON and always contains the fields: code, apiCode and reason. The error message will be similar to this example:

{
     "code": 400,
     "apiCode": 400208,
     "reason": "Invalid Request Method, only GET/POST supported"
}

Error Codes

In addition to human-readable error messages, an error response contains two numeric error codes that a client program can use to identify errors. The “code” will be the same as the HTTP Status Code. The “apiCode” is the more detailed Landslide Error Code, made up of 6 digits, the first three are the HTTP Status Code, and together with the last three uniquely identify the error within Landslide. The common error codes will be listed with each command later in this document. There may be some codes that are not documented at this time and definitely more error messages than described. Many of the undocumented error messages are the same normal error messages you get within Landslide.

The 401 Responses do not include the JSON, they are just generic HTTP responses. The “Error Text” described is just the returned HTTP Phrase/Reason.

Generic Errors

HTTP Status	Numeric Code	Error Text	Description
400	400000	Invalid URL, RESTful API starts at /api	Invalid URL requested
403	403199	A valid startup code must be sent to enable TAS	The Landslide license requires a Startup Code, which has not been provided yet
401	N/A	You must login with Landslide Username:Password	Authorization header is missing
401	N/A	You must use Basic Auth with Landslide Username:Password	Authorization is not BASIC
401	N/A	Invalid username/password, not Base64 Encoded Username:Password	Authorization value is not Base64 encoded properly
401	N/A	Invalid username/password, Authentication Failure	Failed Authentication
401	N/A	User's password has expired, please see System Administrator	User’s password has expired

Username and Password must be passed in each call.

Response Headers

All RESTful API response messages will include the following HTTP Headers:

Cache-Control: no-cache, no-store
Api-Version: <VERSION> (currently 5.0)
Tas-Version: <VERSION> (e.g. 15.7.0.1)
Content-Type: <CONTENT-TYPE> (e.g. application/json or application/binary)
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: X-Landslide-License-Expires
X-Landslide-License-Expires: <DATE>

For an explanation of Cache-Control, Content-Type, see https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html
For an explanation of Access-Control-Allow-Origin, see https://en.wikipedia.org/wiki/Cross-origin_resource_sharing

Api-Version indicates the current general version of the API on the TAS that sent the response. The value will only increase when there are major changes to the API.
Tas-Version indicates the version of the TAS that sent the response.

X-Landslide-License-Expires indicates the date the License Expires or else for perpetual license, it will be empty or indicate 12/31/2100.

As new features are added, the “Since” indicators in this document will be updated to match these version fields.

Use TAS Setting (Edit Settings) tas_fqdn to set the HOST that the TAS will use for all URLs it builds in APIs and external notifications (Kafka/SNMP), in lieu of IP-Address.

When the TAS is started, the startup log will print information about IP Address and Hostname: TAS FQDN set to: test.tas.spirent.com

Examples of these headers are included in the Example Responses in this document. Some examples were executed on older versions of Landslide and do not include all of the headers.

Response when using an expiring license:

{
"adminMessage": "",
"advancedSecurity": false,
"currentTime": "2023-07-25 12:37:38-05 CDT",
"landslideVersion": "TAS-99.9.0.2023-07-25.2drd-(internal)",
"licenseExpires": "05/22/2025",
"licenseFile": "L11932_99.9_UI_Team_vTASs_2023-05-22_0947.sql",
"licenseId": "11932",}

Common Actions Via RESTful API

This section describes common actions to execute and the API function to use.

For Creating, Modifying, or Deleting Users, SUTs, TestServers, DMFs, TestDataFiles, Global Meta Data, or other objects, in general all follow the same standard pattern. For creates you POST an HTTP Message to the collection resource, e.g. POST api/testServers/. For modify you POST an HTTP Message to the specific object, e.g. POST /api/testServers/5. For deletes you DELETE the resource directly, e.g. DELETE /api/testServers/5. To query/retrieve information you query either the collection, e.g. /api/testServers, or the specific resource /api/testServers/<ID>. If you know the object you are interested in, you can find the respective sub section in RESTful API Functions.

To recycle, back up or restore a test server, you POST to /api/testServers/<ID> with “action” URL argument. See POST testServers/<ID>. Configuring a TS (TS-Config) is not supported via the RESTful API; you must use the Tcl API or the TS CLI directly.

To start tests, you POST to the /api/runningTests resource. You can also override much of the test session configuration by providing JSON in the body of the post. See POST runningTests/.

To command test sessions to stop, abort, or continue, you POST to the specific test by RUN ID, /api/runningTests/<ID>, with a sp007ecific “action” URL argument. See POST runningTests/<ID>.

To command test cases, to change parameters, or to pause/resume or change DMF rates (update), send ODCs, directly command test cases, or use the command sequencer, you also POST to the specific test by RUN ID, /api/runningTests/<ID>, with a specific “action” URL argument, and any other required information in the JSON body. See POST runningTests/<ID>.

Comparison of REST Request Example Formats

The following are three examples of the same request to create a new port object:

Curl command line

curl –X POST \
  –u user:password  \
  –d "{ \"library\": -39, \"name\": \"Example_Test\" }" \
  http://tas-ip-address:8080/api/runningTests

Raw HTTP request

POST /api/runningTests/ HTTP/1.1
  User-Agent: curl/7.22.0
  Host: tas-ip-address
  Accept: application/json
  Authorization: BASIC ABCDF123456
  Content-Length: 46
  Content-Type: application/json

  {  "library": -39, "name": "Example_Test" }

Python

headers = {
     'Accept': 'application/json',
     'Authorization': 'BASIC ABCDFER1232355'
     'Content-type': 'application/json'
  }
  body = "{ \"library\": -39, \"name\": \"Example_Test\" }"

  conn = httplib.HTTPConnection(tas-ip-address, 8080)
  conn.connect()
  conn.request('POST', '/api/runningTests/', body, headers

Swagger UI

Landslide Home Page - Swagger UI- This website contains reference information about the Landslide Restful API system.

Home Page for Swagger UI:

RESTful API - Swagger-UI to TAS for self-documenting REST API.

Initially all operations will be hidden via Hide all operations.

Select :

Hide all operations (default). All supported operations will be hidden as is shown above.
List all operations - List all supported operation per RESTful API Function. Example:
Expand all operations - Expand all the supported operations per RESTful API Function. Example: