Service Virtualization API v3

This page describes using the Service Virtualization API v3 to create and manage virtual services. This API was added in 10.5.
dts106
This page describes using the Service Virtualization API v3 to create and manage virtual services.
2
The primary difference between Service Virtualization API v3 and previous APIs is that the operations use names rather than IDs for the parameters.

Overview
Requirements
  • The DevTest Registry must be running.
  • A Virtual Service Environment (VSE) must be running.
  • API Authentication must use the DevTest user credentials.
Endpoint
The root URL for this API is:
Authentication
This API requires an authentication using the
DevTest
or LDAP credentials. Use the Authorization request header for authentication. The following is an example using curl:
curl -X GET -H "Authorization: Basic XXXXXXXXXXXXX" -H "Cache-Control: no-cache" "http://localhost:1505/lisa-virtualize-invoke/api/v3/vses"
Reference
For more reference, a SWAGGER framework is set up in the following URL for documentation and testing purposes:
http://localhost:1505/lisa-virtualize-invoke/api/v3/swagger-ui
Parameters
The following table is a list of parameters that are used in this document:
Parameter
Description
{vseName}
The VSE server name
{virtualServiceName}
The Virtual Service name
Glossary
VS:
Virtual Service
VSE:
Virtual Service Environment
Response Codes
The following table is a list of response codes that this API returns:
Code
Description
200
Successful
400
Bad request (invalid input data)
404
Not Found
500
Server Error
Sample Swagger Documentation
This is an example of the Swagger documentation for Service Virtualization API v3 that you can find at the following URL:
SampleSwaggerAPIv3.png
Retrieve Information for a Virtual Service Environment based on Status
GET /vses
This endpoint retrieves information about VSEs and their corresponding virtual services based on the status selected in the query parameter.
GET VSEs Swagger example
The only required parameter is
status
. Select Active to only return VSEs in the Active state. Select Inactive to only return VSEs in the Inactive state. Select Both to return all VSEs regardless of their state.
The following optional parameters require additional explanation:
dateTimeFrom:
Specifies the starting date of the time period to return in the format MM-dd-yyyy hh:mm:ss.
dateTimeTo:
Specifies the ending date of the time period to return in the format MM-dd-yyyy hh:mm:ss. By default, the request runs based on the last thirty days.
sortBy:
Specifies whether to sort by VSE Name or Life Time Transaction Count. The default value is VSE Name.
You can receive the response content in JSON or XML. You can download the returned response from the Swagger UI.
Here is an example response that returned 3 VSEs in the Inactive state:
The response changes based on the status selection.
{ "totalVSEsCount": 3, "vseList": [ { "consoleURL": "http://c02rl7umg8wn.dhcp.broadcom.net:1505/index.html", "fullName": "tcp://C02RL7UMG8WN:2013/VSE", "host": "tcp://C02RL7UMG8WN:2013/VSE", "lastEventOccurred": "08-05-2019 12:15:42", "lifetimeTransactionCount": 0, "name": "VSE", "rollingTransactionCount": 0, "status": "Inactive", "upTime": 401268000, "virtualServiceCount": 2, "virtualServiceList": [ { "modelName": "kioskV5", "name": "kioskV5", "status": "DOWN", "transactionCount": 0 }, { "modelName": "API_Test_23", "name": "API_Test_23", "status": "DOWN", "transactionCount": 0 } ] }, { "consoleURL": "http://c02rl7umg8wn.dhcp.broadcom.net:1505/index.html", "fullName": "tcp://c02rl7umg8wn.dhcp.broadcom.net:2013/VSE", "host": "tcp://c02rl7umg8wn.dhcp.broadcom.net:2013/VSE", "lastEventOccurred": "08-06-2019 11:07:04", "lifetimeTransactionCount": 0, "name": "VSE", "rollingTransactionCount": 0, "status": "Inactive", "upTime": 81482000, "virtualServiceCount": 2, "virtualServiceList": [ { "modelName": "kioskV5", "name": "kioskV5", "status": "DOWN", "transactionCount": 0 }, { "modelName": "API_Test_23", "name": "API_Test_23", "status": "DOWN", "transactionCount": 0 } ] }, { "consoleURL": "http://c02rl7umg8wn.dhcp.broadcom.net:1505/index.html", "fullName": "tcp://c02rl7umg8wn.dhcp.broadcom.net:2017/VSE1", "host": "tcp://c02rl7umg8wn.dhcp.broadcom.net:2017/VSE1", "lastEventOccurred": "07-25-2019 17:05:37", "lifetimeTransactionCount": 0, "name": "VSE1", "rollingTransactionCount": 0, "status": "Inactive", "upTime": 2062000, "virtualServiceCount": 0, "virtualServiceList": [] } ] }
The
lasteventOccurred
parameter specifies the last time that the status changed. The
uptime
field specifies how long the VSE has been in its current status.
Retrieve Information for a Virtual Service / Generate a MAR File
GET /vses/{vseName}/services/{virtualServiceName}
This endpoint either retrieves information about an existing virtual service or gets the existing virtual service as a MAR file. You control which function is performed by setting the response content type header.
APIv3GET.png
Update a Virtual Service
POST /vses/{vseName}/services/{virtualServiceName}
This endpoint updates an existing virtual service by adding transactions from request/response pairs. It does not support data protocol editing or adding transactions from either WSDL or RAML specifications.
The type of body for post data is form-data.
Pass the keys and values as needed. For example, if a virtual service named
httprest
in
VSE
needs updated responses present in the
httprest.zip
file, pass the fields as shown below.
vseName: VSE
virtualServiceName: httprest
deploy: true
inputFile1: <user_home>/httprest.zip
inputFile1/inputFile2 are not strict keywords. The keywords can be of any name as the data we are passing is of form-data
Example of config object for create along with port and SSL information
{
"virtualService":{
"version":"2",
"name": "swaggertest273a2", "description": "Invoke API V3", "status": "", "capacity": "1", "thinkScale": "200", "autoRestart": "false", "startOnDeploy": "true", "groupTag": "test"
},
"transportProtocol":{
"typeId":"HTTP",
"basePath":"/",
"useGateway":true,
"hostHeaderPassThrough":false,
"recordingEndpoint":{
"useSSL":true,
"host":"",
"port":"28654",
"sslConfig":{
"keystoreFile":"/Applications/CA/DevTest105/webreckeys.ks",
"keystorePassword":"passphrase",
"alias":"lisa",
"aliasPassword":"passphrase"
}
}
},
"dataProtocol":{
"forRequest":true,
"typeId":"RESTDPH"
}
}
If you need to overwrite a virtual service’s response, pass the config as {“transportProtocol":{"overwriteTxns":true}} in the Configuration tab of the update virtual service API. If you need to merge the response,
"duptxns": true
is required in the create virtual service API and
"overwriteTxns”: false
is given while updating a virtual service.
APIv3POST-virtualServiceName.png
Create a Virtual Service
POST /vses/{vseName}/services
This endpoint creates a new virtual service. It provides a universal creation point that is able to do the following:
  • Create virtual services from definition files, including Swagger, WSDL, RAML, and Request/Response Pairs
  • Produce a MAR file
  • Deploy the created virtual service
Example of a config object for create, including port and SSL information:
{
"virtualService":{
"version":"2",
"name": "swaggertest273a2", "description": "Invoke API V3", "status": "", "capacity": "1", "thinkScale": "200", "autoRestart": "false", "startOnDeploy": "true", "groupTag": "test"
},
"transportProtocol":{
"typeId":"HTTP",
"basePath":"/",
"useGateway":true,
"hostHeaderPassThrough":false,
"recordingEndpoint":{
"useSSL":true,
"host":"",
"port":"28654",
"sslConfig":{
"keystoreFile":"/Applications/CA/DevTest105/webreckeys.ks",
"keystorePassword":"passphrase",
"alias":"lisa",
"aliasPassword":"passphrase"
}
}
},
"dataProtocol":{
"forRequest":true,
"typeId":"RESTDPH"
}
}
The type of body for post data is form-data.
Pass the keys and values as needed. For example, if a virtual service named
httprest
in
VSE
needs updated responses present in the
httprest.zip
file, pass the fields as shown below.
vseName: VSE
virtualServiceName: httprest
deploy: true
inputFile1: <user_home>/httprest.zip
inputFile1/inputFile2 are not strict keywords. The keywords can be any name because the data we are passing is form-data.
APIv3POST-services.png
Note:
The
ramlurl
parameter supports both the 0.8 and 1.0 specifications.
Configuring the Virtual Service
The configuration is mandatory and can be provided in the following ways:
  • The
    config
    form parameter in the POST request.
  • A separate JSON file that is added to the request as a file in the body of the POST request.
Example configuration in JSON format:
{
"virtualService": {
"version": "2",
"name": "API_Test_5",
"description": "Invoke API V2",
"status": ""
},
"transportProtocol": {
"typeId": "HTTP",
"basePath": "/",
"useGateway": true,
"hostHeaderPassThrough": false
},
"dataProtocol": {
"forRequest": true,
"typeId": "RESTDPH"
}
}
Extending Configuration with Custom REST Rules
By default,
DevTest
automatically generates REST rules for all HTTP REST services. You can override these rules in JSON configuration.
{
"virtualService": {
"version": "2",
"name": "API_Test_5",
"description": "Invoke API V2",
"status": ""
},
"transportProtocol": {
"typeId": "HTTP",
"basePath": "/",
"useGateway": true,
"hostHeaderPassThrough": false
},
"dataProtocol": {
"forRequest": true,
"typeId": "RESTDPH",
"config": {
"rules": [
{
"valid": true,
"uri": "GET /inventory/cars/"
},
{
"valid": true,
"uri": "GET /inventory/carMake/index.json/"
},
{
"valid": true,
"uri": "GET /inventory/carDealer/index/"
},
{
"valid": true,
"uri": "GET /inventory/carInventory/{URLPARAM0}/"
},
{
"valid": true,
"uri": "GET /inventory/carMake/{URLPARAM0}/models.json/"
},
{
"valid": true,
"uri": "GET /loan/lisa.simpson/"
},
{
"valid": true,
"uri": "POST /loan/"
},
{
"valid": true,
"uri": "GET /html",
"editing": true
}
]
}
}
}
Create a Virtual Service from a Swagger Specification
Add the parameter
swaggerurl
as the form parameter or add a JSON definition file to the attachment.
Create a Virtual Service from a RAML Specification
Add the parameter
ramlurl
as the form parameter or add a JSON definition file to the attachment.
Create a Virtual Service from a WADL Specification
Add the parameter
waldurl
as the form parameter or add a JSON definition file to the attachment.
Create a Virtual Service from Request/Response Pairs
Attach the request/response pair files to the body of the request. The request/response pairs are processed, and a virtual service is created from them.