apis » gateway » 1.1
Riverbed Cascade Gateway REST API
Created Nov 12, 2024 at 10:02 PM

Overview

Overview

The documentation pages in this section describe the RESTful APIs included with Cascade Gateway products. It is assumed that the reader has practical knowledge of RESTful APIs, so the documentation does not go into detail about what REST is and how to use it. Instead the documentation focuses on what data can be accessed and how to access it.

The following information can be accessed via the API:

  • Perform System operations
  • Information about system users

Details about REST resources can be found in the Resources section. This overview continues with how to run reports and retrieve data from them.

Authentication

All REST requests must be authenticated. The Authentication section of the Common 1.0 API describes which authentication methods are presently supported. There are also examples that show how to use each of the different authentication methods.

Resources

Ping: Ping

Simple test of service availability.

GET https://{device}/api/gateway/1.1/ping
Authorization

This request requires authorization.

Response Body

On success, the server does not provide any body in the responses.

Users: List users

Get a list of user accounts.

GET https://{device}/api/gateway/1.1/users
Authorization

This request requires authorization.

Response Body

On success, the server returns a response body with the following structure:

  • JSON
[
  {
    "authentication_type": string,
    "authorization_type": string,
    "enabled": boolean,
    "first_name": string,
    "id": number,
    "last_access": number,
    "last_authentication": number,
    "last_login": number,
    "last_name": string,
    "login_timeout": number,
    "role": string,
    "username": string,
    "view_packet_details": boolean,
    "view_user_information": boolean
  }
]

Example:
[
  {
    "username": "admin", 
    "last_authentication": 1352313328, 
    "first_name": "Jonh", 
    "last_name": "Smith", 
    "authorization_type": "Local", 
    "enabled": true, 
    "view_user_information": true, 
    "authentication_type": "Local", 
    "role": "Administrator", 
    "login_timeout": 900, 
    "last_login": 1352313328, 
    "last_access": 1352313328, 
    "id": 123
  }, 
  {
    "username": "admin2", 
    "last_authentication": 1352313328, 
    "first_name": "Mark", 
    "last_name": "Greg", 
    "authorization_type": "Local", 
    "enabled": true, 
    "view_user_information": true, 
    "authentication_type": "Local", 
    "role": "Administrator", 
    "login_timeout": 900, 
    "last_login": 1352313328, 
    "last_access": 1352313328, 
    "id": 124
  }
]
Property Name Type Description Notes
users <array of <object>> List of user accounts on the system.
users[user] <object> User account.
users[user].authentication_type <string> Type of authentication for the user, such as Local or RADIUS. Values: Local, RADIUS
users[user].authorization_type <string> Type of authorization for the user, such as Local or RADIUS. Values: Local, RADIUS
users[user].enabled <boolean> Boolean flag indicating if the user account is enabled.
users[user].first_name <string> First name of the user.
users[user].id <number> Numeric ID of the user that the system uses internally and in the API.
users[user].last_access <number> Time of last access to the system. Unix time (epoch).
users[user].last_authentication <number> Time of last authentication. Unix time (epoch).
users[user].last_login <number> Time of last login. Unix time (epoch).
users[user].last_name <string> Last name of the user.
users[user].login_timeout <number> Timeout (in seconds) during which the user cannot log in to the system because of security policies.
users[user].role <string> Role of the user. Defines permissions. Values: Developer, Administrator, Operator, Monitor, Event_Viewer, Dashboard_Viewer
users[user].username <string> User name (short name) that identifies the user to the system, such as 'admin'.
users[user].view_packet_details <boolean> Boolean flag indicating if the user has access to packet data. Optional
users[user].view_user_information <boolean> Boolean flag indicating if the user has access to identity information, such as Active Directory information. Optional

Users: Test RADIUS user

Test a RADIUS user.

GET https://{device}/api/gateway/1.1/users/radius/test_user?username={string}&password={string}
Authorization

This request requires authorization.

Parameters
Property Name Type Description Notes
username <string> RADIUS username.
password <string> RADIUS username password.
Response Body

On success, the server returns a response body with the following structure:

  • JSON
{
  "attributes": [
    {
      [attr]: string
    }
  ],
  "authenticated": boolean,
  "authorized": boolean,
  "details": string,
  "error_message": string,
  "permission": string,
  "permission_id": string,
  "role": string,
  "role_id": number,
  "server_ip": string
}

Example:
{
  "authenticated": true, 
  "permission": "", 
  "permission_id": "", 
  "error_message": "", 
  "role_id": 0, 
  "role": "", 
  "authorized": false, 
  "server_ip": "10.38.8.112:1812", 
  "attributes": [
    {
      "25": "operatorClass"
    }, 
    {
      "25": "monitorClass"
    }, 
    {
      "25": "eventviewerClass"
    }, 
    {
      "17164": "unMappedRole"
    }, 
    {
      "17164": "monitorCascade"
    }, 
    {
      "17164": "eventviewerCascade"
    }, 
    {
      "17164": "dashboardCascade"
    }, 
    {
      "25": "DBAccess"
    }, 
    {
      "25": "dashboardClass"
    }, 
    {
      "17164": "AbC10~!@#$%^&*()_+{}|[]:;<>?/.'z"
    }, 
    {
      "17164": "operatorCascade"
    }, 
    {
      "LOGIN_RADIUS_SERVER": "10.38.8.112:1812"
    }, 
    {
      "25": "adminClass1"
    }, 
    {
      "25": "unMappedClass"
    }, 
    {
      "25": "eventviewerClass"
    }, 
    {
      "17164": "adminCascade"
    }
  ], 
  "details": "Using 10.38.8.112:1812 - Unable to match a role."
}
Property Name Type Description Notes
test_server <object> RadiusTestUserResponse object.
test_server.attributes <array of <object>> Radius Attributes List object.
test_server.attributes[attribute] <object> RADIUS attributes map. Optional
test_server.attributes[attribute][attr] <string> RADIUS attribute value.
test_server.authenticated <boolean> Flag indication if the RADIUS user was authenticated.
test_server.authorized <boolean> Flag indication if the RADIUS user was authorized (as Administrator, Monitor, etc).
test_server.details <string> RADIUS user test details.
test_server.error_message <string> Error message.
test_server.permission <string> Matched permission name.
test_server.permission_id <string> Matched permission ID.
test_server.role <string> Matched role name.
test_server.role_id <number> Matched role ID.
test_server.server_ip <string> RADIUS Server IP Address.

Users: Test RADIUS server

Test the connection to a RADIUS server.

GET https://{device}/api/gateway/1.1/users/radius/test_server
Authorization

This request requires authorization.

Parameters
Property Name Type Description Notes
server <string> RADIUS server identifier, example server=IP:PORT.
Response Body

On success, the server returns a response body with the following structure:

  • JSON
{
  "message": string,
  "success": boolean
}

Example:
{
  "message": "RADIUS connection attempt succeeded", 
  "success": true
}
Property Name Type Description Notes
test_server <object> RadiusTestServerResponse object.
test_server.message <string> Response message.
test_server.success <boolean> Flag indication if the RADIUS server test was successful.

Users: Re-authenticate user

Re-authenticate a user account. Requires basic authentication.

GET https://{device}/api/gateway/1.1/users/re_authenticate
Authorization

This request requires authorization.

Response Body

On success, the server does not provide any body in the responses.

Users: Get user

Get a user account by user ID.

GET https://{device}/api/gateway/1.1/users/{user_id}
Authorization

This request requires authorization.

Response Body

On success, the server returns a response body with the following structure:

  • JSON
{
  "authentication_type": string,
  "authorization_type": string,
  "enabled": boolean,
  "first_name": string,
  "id": number,
  "last_access": number,
  "last_authentication": number,
  "last_login": number,
  "last_name": string,
  "login_timeout": number,
  "role": string,
  "username": string,
  "view_packet_details": boolean,
  "view_user_information": boolean
}

Example:
{
  "username": "admin", 
  "last_authentication": 1352313328, 
  "first_name": "Jonh", 
  "last_name": "Smith", 
  "authorization_type": "Local", 
  "enabled": true, 
  "view_user_information": true, 
  "authentication_type": "Local", 
  "role": "Administrator", 
  "login_timeout": 900, 
  "last_login": 1352313328, 
  "last_access": 1352313328, 
  "id": 123
}
Property Name Type Description Notes
user <object> User account.
user.authentication_type <string> Type of authentication for the user, such as Local or RADIUS. Values: Local, RADIUS
user.authorization_type <string> Type of authorization for the user, such as Local or RADIUS. Values: Local, RADIUS
user.enabled <boolean> Boolean flag indicating if the user account is enabled.
user.first_name <string> First name of the user.
user.id <number> Numeric ID of the user that the system uses internally and in the API.
user.last_access <number> Time of last access to the system. Unix time (epoch).
user.last_authentication <number> Time of last authentication. Unix time (epoch).
user.last_login <number> Time of last login. Unix time (epoch).
user.last_name <string> Last name of the user.
user.login_timeout <number> Timeout (in seconds) during which the user cannot log in to the system because of security policies.
user.role <string> Role of the user. Defines permissions. Values: Developer, Administrator, Operator, Monitor, Event_Viewer, Dashboard_Viewer
user.username <string> User name (short name) that identifies the user to the system, such as 'admin'.
user.view_packet_details <boolean> Boolean flag indicating if the user has access to packet data. Optional
user.view_user_information <boolean> Boolean flag indicating if the user has access to identity information, such as Active Directory information. Optional

System: Stop all processes

Stop all system processes. The operation is asynchronous. Use "GET system/status" to poll for status. On Enterprise systems, stop system processes on all modules.

POST https://{device}/api/gateway/1.1/system/stop
Authorization

This request requires authorization.

Request Body

Do not provide a request body.

Response Body

On success, the server does not provide any body in the responses.

System: Kill all processes

Kill all system processes. The operation is asynchronous. Use "GET system/status" to poll for status. On Enterprise systems, kill system processes on all modules. Warning: this operation can result in data being corrupted.

POST https://{device}/api/gateway/1.1/system/kill
Authorization

This request requires authorization.

Request Body

Do not provide a request body.

Response Body

On success, the server does not provide any body in the responses.

System: Shutdown

Shutdown the system. The operation is asynchronous.

POST https://{device}/api/gateway/1.1/system/shutdown
Authorization

This request requires authorization.

Request Body

Do not provide a request body.

Response Body

On success, the server does not provide any body in the responses.

System: Get status of all processes

Get status of all system processes. On Enterprise systems, get system process statuses on all modules.

GET https://{device}/api/gateway/1.1/system/status
Authorization

This request requires authorization.

Response Body

On success, the server returns a response body with the following structure:

  • JSON
[
  {
    "module_ipaddr": string,
    "module_name": string,
    "process_id": string,
    "process_name": string,
    "status": string
  }
]

Example:
[
  {
    "process_id": "25096", 
    "process_name": "memmonitor", 
    "status": "Running"
  }, 
  {
    "process_name": "healthd", 
    "status": "Stopped"
  }, 
  {
    "process_id": "25092", 
    "process_name": "diskmon", 
    "status": "Running"
  }, 
  {
    "process_id": "25123", 
    "process_name": "dispatcher", 
    "status": "Running"
  }, 
  {
    "process_name": "analyzer", 
    "status": "Stopped"
  }
]
Property Name Type Description Notes
status <array of <object>> SystemStatus object.
status[process] <object> SystemProcess object.
status[process].module_ipaddr <string> Module IP Address. Available on Enterprise systems only. Optional
status[process].module_name <string> Module name. Available on Enterprise systems only. Optional
status[process].process_id <string> Process ID. Optional
status[process].process_name <string> Process name.
status[process].status <string> Process status. Values: Running, Stopped

System: Start all processes

Start all system processes. The operation is asynchronous. Use "GET system/status" to poll for status. On Enterprise systems, start system processes on all modules.

POST https://{device}/api/gateway/1.1/system/start
Authorization

This request requires authorization.

Request Body

Do not provide a request body.

Response Body

On success, the server does not provide any body in the responses.

System: Restart all processes

Restart all system processes. The operation is asynchronous. Use "GET system/status" to poll for status. On Enterprise systems, stop system processes on all modules.

POST https://{device}/api/gateway/1.1/system/restart
Authorization

This request requires authorization.

Request Body

Do not provide a request body.

Response Body

On success, the server does not provide any body in the responses.

System: Reboot

Reboot the system. The operation is asynchronous.

POST https://{device}/api/gateway/1.1/system/reboot
Authorization

This request requires authorization.

Request Body

Do not provide a request body.

Response Body

On success, the server does not provide any body in the responses.

System: Stop all processes (one module)

Stop all system processes on one module on Enterprise systems. The operation is asynchronous. Use "GET system/{module}/status" to poll for status. The {module} can be either the IP Address or the module name.

POST https://{device}/api/gateway/1.1/system/{module}/stop
Authorization

This request requires authorization.

Request Body

Do not provide a request body.

Response Body

On success, the server does not provide any body in the responses.

System: Kill all processes (one module)

Kill all system processes on one module on Enterprise systems. The operation is asynchronous. Use "GET system/{module}/status" to poll for status. The {module} can be either the IP Address or the module name. Warning: This operation can result in data being corrupted.

POST https://{device}/api/gateway/1.1/system/{module}/kill
Authorization

This request requires authorization.

Request Body

Do not provide a request body.

Response Body

On success, the server does not provide any body in the responses.

System: Get status of all processes (one module)

Get status of all system processes on one module on Enterprise systems. The {module} can be either the IP Address or the module name.

GET https://{device}/api/gateway/1.1/system/{module}/status
Authorization

This request requires authorization.

Response Body

On success, the server returns a response body with the following structure:

  • JSON
[
  {
    "module_ipaddr": string,
    "module_name": string,
    "process_id": string,
    "process_name": string,
    "status": string
  }
]

Example:
[
  {
    "process_id": "25096", 
    "process_name": "memmonitor", 
    "status": "Running"
  }, 
  {
    "process_name": "healthd", 
    "status": "Stopped"
  }, 
  {
    "process_id": "25092", 
    "process_name": "diskmon", 
    "status": "Running"
  }, 
  {
    "process_id": "25123", 
    "process_name": "dispatcher", 
    "status": "Running"
  }, 
  {
    "process_name": "analyzer", 
    "status": "Stopped"
  }
]
Property Name Type Description Notes
status <array of <object>> SystemStatus object.
status[process] <object> SystemProcess object.
status[process].module_ipaddr <string> Module IP Address. Available on Enterprise systems only. Optional
status[process].module_name <string> Module name. Available on Enterprise systems only. Optional
status[process].process_id <string> Process ID. Optional
status[process].process_name <string> Process name.
status[process].status <string> Process status. Values: Running, Stopped

System: Start all processes (one module)

Start all system processes on one module on Enterprise systems. The operation is asynchronous. Use "GET system/{module}/status" to poll for status. The {module} can be either the IP Address or the module name.

POST https://{device}/api/gateway/1.1/system/{module}/start
Authorization

This request requires authorization.

Request Body

Do not provide a request body.

Response Body

On success, the server does not provide any body in the responses.

System: Restart all processes (one module)

Restart all system processes on one module on Enterprise systems. The operation is asynchronous. Use "GET system/{module}/status" to poll for status. The {module} can be either the IP Address or the module name.

POST https://{device}/api/gateway/1.1/system/{module}/restart
Authorization

This request requires authorization.

Request Body

Do not provide a request body.

Response Body

On success, the server does not provide any body in the responses.

Error Codes

In the event that an error occurs while processing a request, the server will respond with appropriate HTTP status code and additional information in the response body:

{
     "error_id":   "{error identifier}",
     "error_text": "{error description}",
     "error_info": {error specific data structure, optional}
}

The table below lists the possible errors and the associated HTTP status codes that may returned.

Error ID HTTP Status Comments
INTERNAL_ERROR 500 Internal server error.
AUTH_REQUIRED 401 The requested resource requires authentication.
AUTH_INVALID_CREDENTIALS 401 Invalid username and/or password.
AUTH_INVALID_SESSION 401 Session ID is invalid.
AUTH_EXPIRED_PASSWORD 403 The password must be changed. Access only to password change resources.
AUTH_DISABLED_ACCOUNT 403 Account is either temporarily or permanently disabled.
AUTH_FORBIDDEN 403 User is not authorized to access the requested resource.
AUTH_INVALID_TOKEN 401 OAuth access token is invalid.
AUTH_EXPIRED_TOKEN 401 OAuth access token is expired.
AUTH_INVALID_CODE 401 OAuth access code is invalid.
AUTH_EXPIRED_CODE 401 OAuth access code is expired.
RESOURCE_NOT_FOUND 404 Requested resource was not found.
HTTP_INVALID_METHOD 405 Requested method is not available for this resource.
HTTP_INVALID_HEADER 400 An HTTP header was malformed.
REQUEST_INVALID_INPUT 400 Malformed input structure.
URI_INVALID_PARAMETER 400 URI parameter is not supported or malformed.
URI_MISSING_PARAMETER 400 Missing required parameter.
Copyright © Riverbed Technology Inc. 2015