Seiko SmartCS REST API User manual

First Edition
Sep 6, 2022
U00147060001
SmartCS REST API Operation Guide
Operation Guide
Operation Guide

U00147060001 Sep 2022
©Seiko Solutions Inc. 2022
Unauthorized reproduction is prohibited.
The contents of this document may be changed without notice.
"SEIKO" is a registered trademark of Seiko Holdings Corporation.
Seiko Solutions does not bear any liability for damage occurring due to the use of this
document and the software described within or for the expenses required to recover from
such damage.

Table of Contents
1Introduction ................................................... 1
1.1 About this document.................................................................................................. 1
1.2 Function overview ...................................................................................................... 2
1.3 SmartCS operation overview ................................................................................... 3
1.4 Operating environment ............................................................................................. 4
2Preparation.................................................... 5
2.1 SmartCS preparation ................................................................................................. 5
2.1.1 Enable and disable REST API functions.......................................................... 5
2.1.2 User creation........................................................................................................ 7
2.1.3 Security ............................................................................................................... 10
2.2 Log information......................................................................................................... 11
2.2.1 REST API access logs ....................................................................................... 11
2.2.2 REST API operation logs.................................................................................. 11
3REST API Functions .......................................... 12
3.1 Request....................................................................................................................... 12
3.1.1 Base URL............................................................................................................. 12
3.1.2 HTTP method ..................................................................................................... 13
3.1.3 Parameters ......................................................................................................... 14
3.2 Authentication ........................................................................................................... 15
3.2.1 Basic authentication ......................................................................................... 15
3.3 Response .................................................................................................................... 16
3.3.1 Status code ........................................................................................................ 16
3.3.2 Common data .................................................................................................... 17
3.4 Common error........................................................................................................... 19
4API Resources and Methods .................................. 21
4.1 SYSTEM....................................................................................................................... 22
4.1.1 /system/version (GET) .................................................................................... 22
4.1.1.1 Overview ..................................................................................................... 22

4.1.1.2 Request........................................................................................................ 22
4.1.1.3 Response..................................................................................................... 23
4.1.1.4 Error ............................................................................................................. 24
4.1.1.5 Execution example .................................................................................... 24
4.2 USERS ......................................................................................................................... 25
4.2.1 /users (GET)....................................................................................................... 25
4.2.1.1 Overview ..................................................................................................... 25
4.2.1.2 Request........................................................................................................ 25
4.2.1.3 Response..................................................................................................... 26
4.2.1.4 Error ............................................................................................................. 27
4.2.1.5 Execution example .................................................................................... 27
4.2.2 /users (POST) .................................................................................................... 28
4.2.2.1 Overview ..................................................................................................... 28
4.2.2.2 Request........................................................................................................ 28
4.2.2.3 Response..................................................................................................... 31
4.2.2.4 Error ............................................................................................................. 31
4.2.2.5 Execution example .................................................................................... 32
4.2.3 /users/{username} (GET) .............................................................................. 33
4.2.3.1 Overview ..................................................................................................... 33
4.2.3.2 Request........................................................................................................ 33
4.2.3.3 Response..................................................................................................... 34
4.2.3.4 Error ............................................................................................................. 35
4.2.3.5 Execution example .................................................................................... 35
4.2.4 /users/{username} (PUT)............................................................................... 36
4.2.4.1 Overview ..................................................................................................... 36
4.2.4.2 Request........................................................................................................ 36
4.2.4.3 Response..................................................................................................... 39
4.2.4.4 Error ............................................................................................................. 39
4.2.4.5 Execution example .................................................................................... 40
4.2.5 /users/{username} (DELETE)........................................................................ 41
4.2.5.1 Overview ..................................................................................................... 41
4.2.5.2 Request........................................................................................................ 41
4.2.5.3 Response..................................................................................................... 42
4.2.5.4 Error ............................................................................................................. 42
4.2.5.5 Execution example .................................................................................... 42
4.2.6 /users/login (GET) ............................................................................................ 43
4.2.6.1 Overview ..................................................................................................... 43
4.2.6.2 Request........................................................................................................ 43

4.2.6.3 Response..................................................................................................... 43
4.2.6.4 Error ............................................................................................................. 44
4.2.6.5 Execution example .................................................................................... 44
4.3 SERIAL ........................................................................................................................ 45
4.3.1 /serial/tty (GET)................................................................................................ 45
4.3.1.1 Overview ..................................................................................................... 45
4.3.1.2 Request........................................................................................................ 45
4.3.1.3 Response..................................................................................................... 46
4.3.1.4 Error ............................................................................................................. 47
4.3.1.5 Execution example .................................................................................... 47
4.3.2 /serial/tty/{ttylist} (GET) ............................................................................... 48
4.3.2.1 Overview ..................................................................................................... 48
4.3.2.2 Request........................................................................................................ 48
4.3.2.3 Response..................................................................................................... 49
4.3.2.4 Error ............................................................................................................. 50
4.3.2.5 Execution example .................................................................................... 51
4.3.3 /serial/tty/{ttylist} (PUT)................................................................................ 52
4.3.3.1 Overview ..................................................................................................... 52
4.3.3.2 Request........................................................................................................ 52
4.3.3.3 Response..................................................................................................... 55
4.3.3.4 Error ............................................................................................................. 55
4.3.3.5 Execution example .................................................................................... 56
4.3.4 /serial/hangup/tty/{ttylist} (POST).............................................................. 57
4.3.4.1 Overview ..................................................................................................... 57
4.3.4.2 Request........................................................................................................ 57
4.3.4.3 Response..................................................................................................... 58
4.3.4.4 Error ............................................................................................................. 58
4.3.4.5 Execution example .................................................................................... 59
4.4 TTYMANAGE ............................................................................................................... 60
4.4.1 /ttymanage (POST) .......................................................................................... 60
4.4.1.1 Overview ..................................................................................................... 60
4.4.1.2 Request........................................................................................................ 60
4.4.1.3 Response..................................................................................................... 63
4.4.1.4 Error ............................................................................................................. 64
4.4.1.5 Execution example .................................................................................... 66
4.5 LOG/HISTORY............................................................................................................ 68
4.5.1 /log/history/command (GET) ......................................................................... 68

4.5.1.1 Overview ..................................................................................................... 68
4.5.1.2 Request........................................................................................................ 68
4.5.1.3 Response..................................................................................................... 69
4.5.1.4 Error ............................................................................................................. 69
4.5.1.5 Execution example .................................................................................... 70
4.5.2 /log/history/console (GET) ............................................................................. 71
4.5.2.1 Overview ..................................................................................................... 71
4.5.2.2 Request........................................................................................................ 71
4.5.2.3 Response..................................................................................................... 72
4.5.2.4 Error ............................................................................................................. 72
4.5.2.5 Execution example .................................................................................... 73
4.5.3 /log/history/ttysend/tty/{ttyno} (GET) ....................................................... 74
4.5.3.1 Overview ..................................................................................................... 74
4.5.3.2 Request........................................................................................................ 74
4.5.3.3 Response..................................................................................................... 75
4.5.3.4 Error ............................................................................................................. 75
4.5.3.5 Execution example .................................................................................... 76
4.5.4 /log/history/webapi (GET) .............................................................................. 77
4.5.4.1 Overview ..................................................................................................... 77
4.5.4.2 Request........................................................................................................ 77
4.5.4.3 Response..................................................................................................... 78
4.5.4.4 Error ............................................................................................................. 78
4.5.4.5 Execution example .................................................................................... 79
4.6 LOG/SERIAL............................................................................................................... 80
4.6.1 /log/serial/tty/{ttyno} (GET) ......................................................................... 80
4.6.1.1 Overview ..................................................................................................... 80
4.6.1.2 Request........................................................................................................ 80
4.6.1.3 Response..................................................................................................... 81
4.6.1.4 Error ............................................................................................................. 81
4.6.1.5 Execution example .................................................................................... 82
4.6.2 /log/serial/files/tty/{ttyno} (GET) ................................................................ 83
4.6.2.1 Overview ..................................................................................................... 83
4.6.2.2 Request........................................................................................................ 83
4.6.2.3 Response..................................................................................................... 84
4.6.2.4 Error ............................................................................................................. 84
4.6.2.5 Execution example .................................................................................... 85
4.6.3 /log/serial/search/tty/{ttyno} (GET)............................................................ 86
4.6.3.1 Overview ..................................................................................................... 86

4.6.3.2 Request........................................................................................................ 86
4.6.3.3 Response..................................................................................................... 87
4.6.3.4 Error ............................................................................................................. 88
4.6.3.5 Execution example .................................................................................... 89
5/ttymanage explanation ...................................... 90
5.1 Instructions and Directions for Use ...................................................................... 90
5.2 Limitations.................................................................................................................. 92
5.3 Operation under each option ................................................................................. 93
5.3.1 sendchar and recvchar operation .................................................................. 93
5.3.2 Operation when recvchar is not configured ................................................ 94
5.3.3 Special sendchar settings ................................................................................... 95
5.3.4 error_detect_on_sendchar operation ......................................................... 103
5.4 List of sendchar sending methods ...................................................................... 105
5.5 Configuring Regular Expressions......................................................................... 107
6Appendix A Accessible API Resources for Each User Authority 109

1
1Introduction
1.1 About this document
This document is the Operation Guide which summarizes the information
that is required when using the SmartCS REST API functions. It lists
information such as the SmartCS settings, specifications of each API
resource, and how to use it, so please refer to this document when using
the REST API functions.
Moreover, this document covers only the SmartCS REST API functions.
The "Instruction Manual" and "Command Reference" contain detailed
explanations of the various SmartCS settings and CLI command details, so
please refer to those documents as needed.

2
1.2 Function overview
This section provides an overview of the SmartCS REST API functions.
SmartCS has so far executed a CLI after logging into a device via telnet or
SSH for settings and information acquisition or the operation of managed
nodes connected to SmartCS. By using the REST API functions, you can
execute each function (processing by each API resource) from various
clients and tools.
・SmartCS information and setting detail acquisition
・SmartCS settings
・Acquisition/search of TTY log information for managed nodes connected
to the serial port of SmartCS
・Execution of operations on managed nodes connected to SmartCS
The REST API communicates using the HTTP protocol, requests and sends
each method and transmission data from the client to specify various
operations with respect to the API resources provided by SmartCS.
SmartCS replies to the client with data according to the HTTP code and
specified operations as a response.
<Representation of the HTTP method and CLI operation during the
request>
HTTP method
Meaning
CLI example
GET
Get the API resource
show
POST
Create the API resource,
etc.
create
PUT Change or update the API
resource
set, unset
DELETE
Delete the API resource
delete

3
<HTTP code example during the response>
HTTP code
Meaning
Description
200
OK
Operation successful
400
Invalid request, etc.
Operation failed
1.3 SmartCS operation overview
This section provides an operation overview of the SmartCS REST API
functions. The REST API functions access each API resource provided by
SmartCS from the client and return a response for each function according
to the request details.
A representation of the SmartCS function processes when a REST API
request is received is shown in the figure and table details below.

4
After the request is received, each CLI function runs and provides each
function. This document explains each API resource specification without
explaining the detailed specifications of each CLI. Because an error
message may be output by the CLI when an operation does not work
properly in some cases, refer to the "Command Reference."
1.4 Operating environment
The SmartCS supports REST API functions in version 3.0 and above. The
API resource specifications for each version are as shown in the following
table.
SmartCS version Base URL
v3.0 http://<IP
address>:<http port
number>/api/v1/
Refer to "Chapter 4 API Resources and Methods" for each address after
the base URL.
Process
Description
Access each API
resource
Accesses each API resource according to the
request from the
client. At that time, it also
checks whether the correct method is specified
and the appropriate user authority is granted,
etc.
Data check Checks whether the data is correct with respect
to the specification of each API resource at the
time of the request.
CLI execution
Executes the CLI command based on the
request data.
Response
Returns the response according to the CLI
execution result.

5
2Preparation
2.1 SmartCS preparation
2.1.1Enable and disable REST API functions
This section describes the SmartCS settings for using the REST API
functions.
(1) Enable the HTTP/HTTPS functions
Enable the SmartCS HTTP/HTTPS functions.
Enabling the HTTP function
(0)NS-2250# enable http
(0)NS-2250#
Enabling the HTTPS function
Setting the HTTP/HTTPS port number
To check whether the setting is enabled or not, check if the specified
setting is enabled or the port number is changed with show service.
In addition, also check whether the TCP port of the specified service
is open with the show tcp command.
A maximum of eight simultaneous sessions can access HTTP/HTTPS
with the REST API functions.
(0)NS-2250# enable https
(0)NS-2250#
(0)NS-2250# set http port 20080
(0)NS-2250# set https port 30443
(0)NS-2250#

6
(2) Enable the TTY manage function
The TTY manage function must be enabled when accessing the
/ttymanage API resource and performing operations on managed
nodes connected to SmartCS.
Enabling the TTY manage function
(0)NS-2250# enable ttymanage
(0)NS-2250#

7
2.1.2User creation
This section explains the process for creating a user to access the
SmartCS REST API functions. A user for accessing each API resource
provided by the REST API functions is a user that belongs to the extusr
group.
A user that belongs to the extusr group can only access via SSH. Such
users cannot access via telnet or console.

8
■SmartCS user groups and executable functions
User group
Description
normal
root
User group that can connect to SmartCS via telnet,
ssh, or console to configure devices and acquire
information.
portusr
User group that can connect to managed nodes
connected to the serial port of the SmartCS via
telnet or ssh and carry out operations.
extusr
User group who can be granted authority by setting.
Even when being not granted authority, this group
has the same authority as normal group users. The
authorities which can be granted are the same
command execution authority (administrator
authority) as root group users and the tty manage
object command execution authority (authority of
tty manage function).
■normal
Able to access functions within those provided by
the API resources that can be executed with CLI
normal user authority (show an
d other status
display commands).
■root
Able to access functions within those provided by
the API resources that can be executed with CLI
administrator authority (create, set, unset, delete,
and other configuration commands).
■ttymanage
Able to search
and acquire the logs of sent and
received information of managed nodes connected
to the serial port and access functions that realize
operations within those functions provided by the
API resources.
setup
verup
log
User group that can connect to SmartCS via FTP or
SFTP (SSH) to send and receive config files, version
update files, and log files.

9
(1) Creating an extusr group user
Create a user that belongs to the extusr user group.
(0)NS-2250# create user api group extusr password
New password: xxxxx
Retype new password: xxxxx
(0)NS-2250#
(2) Setting the administrator authority
Set the administrator authority for the user in the created extusr
group.
(3) Setting the authority of tty manage function and allowing the
accessible port numbers
Set the authority of tty manage function for the user in the created
extusr group and allow the accessible port numbers (ex: 1-4, 16).
(0)NS-2250# set user api permission root on
(0)NS-2250#
(0)NS-2250# set user api permission ttymanage on
(0)NS-2250# set user api port 1-4,16
(0)NS-2250#

10
2.1.3Security
When using the REST API function, set and use the Firewall (ipfilter)
function to strengthen security as needed.
You can restrict access by specifying the TCP port number set to
HTTP/HTTPS.

11
2.2 Log information
2.2.1REST API access logs
You can check the users who accessed using the REST API function with
the show log webapi command.
Checking the latest 5 access logs
(0)NS-2250# show log webapi 5
2022 May 31 15:32:49 [10080] login success: restapi/172.31.8.41:42266
2022 May 31 15:32:49 [10080] logout: restapi/172.31.8.41:42266
2022 May 31 15:32:49 [10080] login success: restapi/172.31.8.41:42268
2022 May 31 15:32:49 [10080] logout: restapi/172.31.8.41:42268
2022 Jun 01 23:49:03 [10080] FAILED LOGIN FROM 172.31.8.41 FOR api,
Authentication failure.
(0)NS-2250#
You can check which username accessed, the IP address, port number of
the connection source, and whether authentication was successful or failed.
2.2.2REST API operation logs
The SmartCS REST API functions ultimately execute the request details
with the CLI. Therefore, you can check the commands executed when
accessing each API resource with the show log command.
When an api user accessed /system/version API resources with the REST
API functions
(0)NS-2250# show log command 5
2022 Jun 1 23:55:08 somebody: show tty
2022 Jun 1 23:55:11 somebody: show user
2022 Jun 1 23:55:12 somebody: su
2022 Jun 1 23:55:20 api: show json version
2022 Jun 1 23:55:26 root: show log command 5
(0)NS-2250#
When an api user used the REST API functions to access /system/version
API resources, you can check whether show json version was executed.

12
3REST API Functions
3.1 Request
3.1.1Base URL
The base URL which accesses the SmartCS REST API functions uses the
following address.
Protocol Base URL
HTTP http://<IP
address>:<http port
number>/api/v1/
HTTPS https://<IP
address>:<https port
number>/api/v1/
The IP address supports both v4 and v6.
The default value of the HTTP port number is 10080, and the default value
of the HTTPS port number is 10443. Port numbers can be changed for each
across a range from 1025 to 65000.
Refer to the Instruction Manual or the Command Reference for how to
change the SmartCS IP address and HTTP/HTTPS port numbers.

13
3.1.2HTTP method
The SmartCS REST API functions support the following HTTP methods.
Method Description
GET Issues a request to acquire information from the specified API
resource.
The operation corresponds to the show related command
under the SmartCS CLI commands.
POST Issues a request to create a new resource in the specified API.
Moreover,
it issues a request to execute a specific operation.
The operation corresponds to the create command, etc. under
the SmartCS CLI commands.
PUT Issues a request to change/modify the specified API resource.
The operation corresponds to the set/unset commands under
the SmartCS CLI commands.
DELETE Issues a request to delete the specified API resource.
The operation corresponds to the create command, etc. under
the SmartCS CLI commands.
The methods which can be specified for each API resource differ, and an
error occurs when an unsupported method is specified. For details, refer to
"Chapter 4 API Resources and Methods."