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
Flow_Sources: List flow sources
Get a list of flow sources.
GET https://{device}/api/gateway/1.4/flow_sourcesAuthorization
This request requires authorization.
Response BodyOn success, the server returns a response body with the following structure:
- JSON
[ { "flows_received_last_min": number, "last_min": number, "ipaddr": string, "versions": string, "flow_type": string } ] Example: [ { "flows_received_last_min": 13299, "ipaddr": "10.32.4.41", "last_min": 1399317542, "flow_type": "NetFlow", "versions": "9.2" }, { "flows_received_last_min": 374, "ipaddr": "10.32.7.31", "last_min": 1399317542, "flow_type": "NetFlow", "versions": "9.2" }, { "flows_received_last_min": 500, "ipaddr": "10.32.7.35", "last_min": 1399317542, "flow_type": "NetFlow", "versions": "9.2" } ]
Property Name | Type | Description | Notes |
---|---|---|---|
GatewayStatsFlowSources | <array of <object>> | List of flow sources. | |
GatewayStatsFlowSources [GatewayStatsFlowSource] |
<object> | Flow source. | Optional |
GatewayStatsFlowSources [GatewayStatsFlowSource]. flows_received_last_min |
<number> | Flows received (last minute). | Optional |
GatewayStatsFlowSources [GatewayStatsFlowSource].last_min |
<number> | Last heard from. | Optional |
GatewayStatsFlowSources [GatewayStatsFlowSource].ipaddr |
<string> | IP address. | |
GatewayStatsFlowSources [GatewayStatsFlowSource].versions |
<string> | Versions. | |
GatewayStatsFlowSources [GatewayStatsFlowSource].flow_type |
<string> | Flow type. |
Flow_Sources: Get flow source
Get a flow source by IP Address.
GET https://{device}/api/gateway/1.4/flow_sources/{ipaddr}Authorization
This request requires authorization.
Response BodyOn success, the server returns a response body with the following structure:
- JSON
{ "flows_received_last_min": number, "last_min": number, "ipaddr": string, "versions": string, "flow_type": string } Example: { "flows_received_last_min": 962, "ipaddr": "10.32.1.41", "last_min": 1392392760, "flow_type": "NetFlow", "versions": "9.2" }
Property Name | Type | Description | Notes |
---|---|---|---|
GatewayStatsFlowSource | <object> | Flow source. | |
GatewayStatsFlowSource. flows_received_last_min |
<number> | Flows received (last minute). | Optional |
GatewayStatsFlowSource.last_min | <number> | Last heard from. | Optional |
GatewayStatsFlowSource.ipaddr | <string> | IP address. | |
GatewayStatsFlowSource.versions | <string> | Versions. | |
GatewayStatsFlowSource.flow_type | <string> | Flow type. |
Flow_Sources: Delete flow source
Delete a flow source by IP Address.
DELETE https://{device}/api/gateway/1.4/flow_sources/{ipaddr}Authorization
This request requires authorization.
Response BodyOn success, the server does not provide any body in the responses.
Ping: Ping
Simple test of service availability.
GET https://{device}/api/gateway/1.4/pingAuthorization
This request requires authorization.
Response BodyOn success, the server does not provide any body in the responses.
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.4/system/{module}/startAuthorization
This request requires authorization.
Request BodyDo not provide a request body.
Response BodyOn 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.4/system/statusAuthorization
This request requires authorization.
Response BodyOn success, the server returns a response body with the following structure:
- JSON
[ { "process_id": string, "process_name": string, "module_name": string, "status": string, "module_ipaddr": 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 |
---|---|---|---|
SystemStatus | <array of <object>> | SystemStatus object. | |
SystemStatus[SystemProcess] | <object> | SystemProcess object. | Optional |
SystemStatus[SystemProcess].process_id | <string> | Process ID. | Optional |
SystemStatus[SystemProcess].process_name | <string> | Process name. | |
SystemStatus[SystemProcess].module_name | <string> | Module name. Available on Enterprise systems only. | Optional |
SystemStatus[SystemProcess].status | <string> | Process status. | Values: Running, Stopped |
SystemStatus[SystemProcess]. module_ipaddr |
<string> | Module IP address. Available on Enterprise systems only. | Optional |
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.4/system/killAuthorization
This request requires authorization.
Request BodyDo not provide a request body.
Response BodyOn 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.4/system/restartAuthorization
This request requires authorization.
Request BodyDo not provide a request body.
Response BodyOn success, the server does not provide any body in the responses.
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.4/system/startAuthorization
This request requires authorization.
Request BodyDo not provide a request body.
Response BodyOn 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.4/system/{module}/restartAuthorization
This request requires authorization.
Request BodyDo not provide a request body.
Response BodyOn 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.4/system/{module}/stopAuthorization
This request requires authorization.
Request BodyDo not provide a request body.
Response BodyOn 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.4/system/{module}/statusAuthorization
This request requires authorization.
Response BodyOn success, the server returns a response body with the following structure:
- JSON
[ { "process_id": string, "process_name": string, "module_name": string, "status": string, "module_ipaddr": 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 |
---|---|---|---|
SystemStatus | <array of <object>> | SystemStatus object. | |
SystemStatus[SystemProcess] | <object> | SystemProcess object. | Optional |
SystemStatus[SystemProcess].process_id | <string> | Process ID. | Optional |
SystemStatus[SystemProcess].process_name | <string> | Process name. | |
SystemStatus[SystemProcess].module_name | <string> | Module name. Available on Enterprise systems only. | Optional |
SystemStatus[SystemProcess].status | <string> | Process status. | Values: Running, Stopped |
SystemStatus[SystemProcess]. module_ipaddr |
<string> | Module IP address. Available on Enterprise systems only. | Optional |
System: Shutdown
Shutdown the system. The operation is asynchronous.
POST https://{device}/api/gateway/1.4/system/shutdownAuthorization
This request requires authorization.
Request BodyDo not provide a request body.
Response BodyOn 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.4/system/rebootAuthorization
This request requires authorization.
Request BodyDo not provide a request body.
Response BodyOn success, the server does not provide any body in the responses.
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.4/system/stopAuthorization
This request requires authorization.
Request BodyDo not provide a request body.
Response BodyOn 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.4/system/{module}/killAuthorization
This request requires authorization.
Request BodyDo not provide a request body.
Response BodyOn 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.4/usersAuthorization
This request requires authorization.
Response BodyOn success, the server returns a response body with the following structure:
- JSON
[ { "enabled": string, "last_name": string, "id": number, "last_login": number, "authentication_type": string, "username": string, "authorization_type": string, "role": string, "first_name": string, "last_access": number, "view_packet_details": string, "last_authentication": number, "view_user_information": string, "login_timeout": number } ] 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. | Optional |
Users[User].enabled | <string> | Boolean flag indicating if the user account is enabled. | |
Users[User].last_name | <string> | Last 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_login | <number> | Time of last login. Unix time (epoch). | |
Users[User].authentication_type | <string> | Type of authentication for the user, such as Local or RADIUS. | Values: Local, Remote |
Users[User].username | <string> | User name (short name) that identifies the user to the system, such as 'admin'. | |
Users[User].authorization_type | <string> | Type of authorization for the user, such as Local or RADIUS. | Values: Local, Remote |
Users[User].role | <string> | Role of the user. Defines permissions. | Values: Developer, Administrator, Operator, Monitor, Event_Viewer, Dashboard_Viewer |
Users[User].first_name | <string> | First name of the user. | |
Users[User].last_access | <number> | Time of last access to the system. Unix time (epoch). | |
Users[User].view_packet_details | <string> | Boolean flag indicating if the user has access to packet data. | Optional |
Users[User].last_authentication | <number> | Time of last authentication. Unix time (epoch). | |
Users[User].view_user_information | <string> | Boolean flag indicating if the user has access to identity information, such as Active Directory information. | Optional |
Users[User].login_timeout | <number> | Timeout (in seconds) during which the user cannot log in to the system because of security policies. |
Users: Re-authenticate user
Re-authenticate user account. Requires basic authentication.
GET https://{device}/api/gateway/1.4/users/re_authenticateAuthorization
This request requires authorization.
Response BodyOn success, the server does not provide any body in the responses.
Users: Get user
User account by user ID.
GET https://{device}/api/gateway/1.4/users/{user_id}Authorization
This request requires authorization.
Response BodyOn success, the server returns a response body with the following structure:
- JSON
{ "enabled": string, "last_name": string, "id": number, "last_login": number, "authentication_type": string, "username": string, "authorization_type": string, "role": string, "first_name": string, "last_access": number, "view_packet_details": string, "last_authentication": number, "view_user_information": string, "login_timeout": number } 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.enabled | <string> | Boolean flag indicating if the user account is enabled. | |
User.last_name | <string> | Last name of the user. | |
User.id | <number> | Numeric ID of the user that the system uses internally and in the API. | |
User.last_login | <number> | Time of last login. Unix time (epoch). | |
User.authentication_type | <string> | Type of authentication for the user, such as Local or RADIUS. | Values: Local, Remote |
User.username | <string> | User name (short name) that identifies the user to the system, such as 'admin'. | |
User.authorization_type | <string> | Type of authorization for the user, such as Local or RADIUS. | Values: Local, Remote |
User.role | <string> | Role of the user. Defines permissions. | Values: Developer, Administrator, Operator, Monitor, Event_Viewer, Dashboard_Viewer |
User.first_name | <string> | First name of the user. | |
User.last_access | <number> | Time of last access to the system. Unix time (epoch). | |
User.view_packet_details | <string> | Boolean flag indicating if the user has access to packet data. | Optional |
User.last_authentication | <number> | Time of last authentication. Unix time (epoch). | |
User.view_user_information | <string> | Boolean flag indicating if the user has access to identity information, such as Active Directory information. | Optional |
User.login_timeout | <number> | Timeout (in seconds) during which the user cannot log in to the system because of security policies. |
Users: Test RADIUS user
Test a RADIUS user.
POST https://{device}/api/gateway/1.4/users/radius/test_user?password={string}&username={string}Authorization
This request requires authorization.
ParametersProperty Name | Type | Description | Notes |
---|---|---|---|
password | <string> | RADIUS password. | |
username | <string> | RADIUS username. |
Provide a request body with the following structure:
- JSON
{ "password": string, "username": string } Example: { "username": "testusername", "password": "testpassword" }
Property Name | Type | Description | Notes |
---|---|---|---|
RemoteTestUserRequest | <object> | RemoteTestUserRequest object. | |
RemoteTestUserRequest.password | <string> | password. | |
RemoteTestUserRequest.username | <string> | user name. |
On success, the server returns a response body with the following structure:
- JSON
{ "role_id": number, "error_message": string, "permission": string, "server_type": number, "role": string, "details": string, "permission_id": string, "server_ip": string, "authenticated": string, "attributes": [ { [prop]: string } ], "authorized": string } Example: { "error_message": "", "authenticated": true, "server_type": 2, "permission_id": "", "permission": "", "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_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 |
---|---|---|---|
RemoteTestUserResponse | <object> | RemoteTestUserResponse object. | |
RemoteTestUserResponse.role_id | <number> | Matched role ID. | |
RemoteTestUserResponse.error_message | <string> | Error message. | |
RemoteTestUserResponse.permission | <string> | Matched permission name. | |
RemoteTestUserResponse.server_type | <number> | Indicates the type of the server being tested: RADIUS(2) or TACACS+(3). | |
RemoteTestUserResponse.role | <string> | Matched role name. | |
RemoteTestUserResponse.details | <string> | Remote user test details. | |
RemoteTestUserResponse.permission_id | <string> | Matched permission ID. | |
RemoteTestUserResponse.server_ip | <string> | Remote Server IP address. | |
RemoteTestUserResponse.authenticated | <string> | Flag indicating if the remote user was authenticated. | |
RemoteTestUserResponse.attributes | <array of <object>> | Attributes of Remote Test User Response. | Optional |
RemoteTestUserResponse.attributes [RemoteAttributes] |
<object> | Remote attribute. | Optional |
RemoteTestUserResponse.attributes [RemoteAttributes][prop] |
<string> | Remote attribute value. | Optional |
RemoteTestUserResponse.authorized | <string> | Flag indicating if the remote user was authorized (as Administrator, Monitor, etc). |
Users: Test TACACS+ server
Test the connection to a TACACS+ server.
GET https://{device}/api/gateway/1.4/users/tacacs/test_serverAuthorization
This request requires authorization.
ParametersProperty Name | Type | Description | Notes |
---|---|---|---|
server | <string> | TACACS+ server identifier, example server=IP:PORT. |
On success, the server returns a response body with the following structure:
- JSON
{ "success": string, "message": string } Example: { "message": "Connection attempt succeeded", "success": true }
Property Name | Type | Description | Notes |
---|---|---|---|
RemoteTestServerResponse | <object> | RemoteTestServerResponse object. | |
RemoteTestServerResponse.success | <string> | Flag indicating if the remote server test was successful. | |
RemoteTestServerResponse.message | <string> | Response message. |
Users: Test TACACS+ user
Test a TACACS+ user.
POST https://{device}/api/gateway/1.4/users/tacacs/test_user?password={string}&username={string}Authorization
This request requires authorization.
ParametersProperty Name | Type | Description | Notes |
---|---|---|---|
password | <string> | TACACS+ password. | |
username | <string> | TACACS+ username. |
Provide a request body with the following structure:
- JSON
{ "password": string, "username": string } Example: { "username": "testusername", "password": "testpassword" }
Property Name | Type | Description | Notes |
---|---|---|---|
RemoteTestUserRequest | <object> | RemoteTestUserRequest object. | |
RemoteTestUserRequest.password | <string> | password. | |
RemoteTestUserRequest.username | <string> | user name. |
On success, the server returns a response body with the following structure:
- JSON
{ "role_id": number, "error_message": string, "permission": string, "server_type": number, "role": string, "details": string, "permission_id": string, "server_ip": string, "authenticated": string, "attributes": [ { [prop]: string } ], "authorized": string } Example: { "error_message": "", "authenticated": true, "server_type": 2, "permission_id": "", "permission": "", "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_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 |
---|---|---|---|
RemoteTestUserResponse | <object> | RemoteTestUserResponse object. | |
RemoteTestUserResponse.role_id | <number> | Matched role ID. | |
RemoteTestUserResponse.error_message | <string> | Error message. | |
RemoteTestUserResponse.permission | <string> | Matched permission name. | |
RemoteTestUserResponse.server_type | <number> | Indicates the type of the server being tested: RADIUS(2) or TACACS+(3). | |
RemoteTestUserResponse.role | <string> | Matched role name. | |
RemoteTestUserResponse.details | <string> | Remote user test details. | |
RemoteTestUserResponse.permission_id | <string> | Matched permission ID. | |
RemoteTestUserResponse.server_ip | <string> | Remote Server IP address. | |
RemoteTestUserResponse.authenticated | <string> | Flag indicating if the remote user was authenticated. | |
RemoteTestUserResponse.attributes | <array of <object>> | Attributes of Remote Test User Response. | Optional |
RemoteTestUserResponse.attributes [RemoteAttributes] |
<object> | Remote attribute. | Optional |
RemoteTestUserResponse.attributes [RemoteAttributes][prop] |
<string> | Remote attribute value. | Optional |
RemoteTestUserResponse.authorized | <string> | Flag indicating if the remote user was authorized (as Administrator, Monitor, etc). |
Users: Test RADIUS server
Test the connection to a RADIUS server.
GET https://{device}/api/gateway/1.4/users/radius/test_serverAuthorization
This request requires authorization.
ParametersProperty Name | Type | Description | Notes |
---|---|---|---|
server | <string> | RADIUS server identifier, example server=IP:PORT. |
On success, the server returns a response body with the following structure:
- JSON
{ "success": string, "message": string } Example: { "message": "Connection attempt succeeded", "success": true }
Property Name | Type | Description | Notes |
---|---|---|---|
RemoteTestServerResponse | <object> | RemoteTestServerResponse object. | |
RemoteTestServerResponse.success | <string> | Flag indicating if the remote server test was successful. | |
RemoteTestServerResponse.message | <string> | Response message. |
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. |