Audit Logs REST API Design.md

Audit Logs REST API Design

GET /V1/CMDB/AuditLogs

This API is used to get audit logs in batch. The response of this API will return a list in JSON format sorted from the latest to the earliest.
Note:
1. The API follows the privilege control of NB system.

Detail Information

Title: Audit Logs API

Version: 05/26/2020

API Server URL: http(s)://IP Address of NetBrain Web API Server/ServicesAPI/API/V1/CMDB/AuditLogs

Authentication:

Type	In	Name
Bearer Authentication	Headers	Authentication token

Request body (*required)

No request body.

Query Parameters (*required)

Name	Type	Description
skip	Integer	The amount of records to be skipped. The value must not be negative. If the value is negative, API throws exception {"statusCode":791001,"statusDescription":"Parameter 'skip' cannot be negative"}. No upper bound for this parameter.
limit	Integer	The up-limit amount of records to return per API call. The value must not be negative. If the value is negative, API throws exception {"statusCode":791001,"statusDescription":"Parameter 'limit' cannot be negative"}. No upper bound for this parameter. If the parameter is not specified in API call, it means there is no limitation setting on the call.
		If only provide skip value, return the device list with 50 devices information start from the skip number. If only provide limit value, return from the first device in DB. If provided both skip and limit, return as required. Error exceptions follow each parameter's description.
		Skip and limit parameters are based on the search result from DB. The "limit" value valid range is 10 - 100, if the assigned value exceeds the range, the server will respond error message: "Parameter 'limit' must be greater than or equal to 10 and less than or equal to 100."
from*	Date	From date. The value must be equal or less than To date.
to*	Date	To date. The value must be equal or greater than From date.
tenant	String	Tenant ID/Name
domain	String	Domain ID/Name
modules	List of String	Options: API Plugin Manager, API Server Manager, API Stub Manager, API Vendor, Calculate Path, CheckPoint OPSEC Manager, Cloud Compare, Crawl Engine Manager, Dashboard, Dashboard Template, Dashboard Widget, Data View Manager, Data View Template, Device Access Policy, Device Driver, Device Group, Device Management, Device Type, Discover, Discovered by SNMP, Discovered Devices, Domain Management, Do-Not-Scan, Duplicated IP and Subnet Manager, Email Server Settings, Execute CLI Commands, External Authentication, Front Server Controller Manager, Gapp Center, GDR Device Property, GDR Interface Property, GDR Interface Type, GDR Module Property, Interface Type, Inventory Report, Knowledge Cloud, Auto Update, License, Login, Logout, Map, Map Layout Manager, Missed Devices, MPLS Cloud, Network Change, Network Definition, Network Pane, Network Settings, One-IP Table, OUI Information, Parser Library, Password Policy, Path, Ping, Platform Management – Network, Platform Management – Technology, Platform Management - Visual Space Template, Port to Protocol List, Private Network Settings, Qapp Center, Qapp Scheduler, Retrieve Live Data, Role, Run Gapp, Run Qapp, Runbook, Runbook Template, Schedule Benchmark Task, Schedule Discovery Task, Security, Share Policy, Single Pane of Glass URL, Site Manager, System Advanced Settings, Task Manager, Tenant Management, Tenant User Authorization, Third Party API Data Engine, Third Party API Device Management, Third Party API Role, Third Party API Topology, Third Party Device Group, Third Party Domain Management, Third Party Event Console, Third Party Map, Third Party Network Settings, Third Party Path, Third Party Schedule Benchmark Task, Third Party Schedule Discovery Task, Third Party Site Manager, Third Party Tenant Management, Third Party Tune Live Access, Topology Link Manager, Traceroute, Tune Live Access, Tune Private CLI Settings, Unclassified Network Devices, Unknown IP, Unknown SNMP SysObjectID, User Management, Variable Mapping, Vendor Model

Headers

Data Format Headers

Name	Type	Description
Content-Type	string	support "application/json"
Accept	string	support "application/json"

Authorization Headers

Name	Type	Description
token	string	Authentication token, get from login API.

Response

Name	Type	Description
statusCode	Integer	Code issued by NetBrain server indicating the execution result.
statusDescription	String	The explanation of the status code.
auditLogs	String[]	List of logs.
auditLogs.time	String	Time.
auditLogs .userName	Integer	Username.
auditLogs .tenantName	String	Tenant name.
auditLogs .domainName	String	Domain name.
auditLogs .machineName	String	Machine name.
auditLogs .ipAddress	String	IP address.
auditLogs .userAgent	String	Browser.
auditLogs .module	String	Module.
auditLogs .message	String	Message.
auditLogs .status	Integer	Status.

Example

{
    "auditLogs":[
        {
            "time":"2020-05-26T14:18:22.785Z",
            "userName":"ui.user1",
            "tenantName":"Initial Tenant",
            "domainName":"Initial Domain",
            "machineName":"pool-96-237-64-80",
            "ipAddress":"96.237.64.81",
            "userAgent":"Chrome",
            "module":"System Advanced Settings",
            "message":"Enable Audit Log",
            "status":0
        },
        {
            "time":"2020-05-26T14:18:42.536Z",
            "userName":"api.user1",
            "tenantName":"",
            "domainName":"",
            "machineName":"pat-149-96-5-12",
            "ipAddress":"149.96.5.12",
            "userAgent":"Unknown",
            "module":"Login",
            "message":"Log in to get an authentication token with username api.user.",
            "status":0
        }
    ],
    "statusCode": 790200,
    "statusDescription":"Success."
}

Response Code

Code	Message	Description
790200	OK
791001	InvalidParameter	The parameter \"From\" and \"To\" is required. The parameter \"From\" is required. The parameter \"To\" is required. The parameter \"To\" must be greater than parameter \"From\". Parameter 'limit' must be greater than or equal to 10 and less than or equal to 100.
793001	InternalServerError	System framework level error