ManagerAPI.md

v# Skywire Manager API Documentation Note: This document is a work in progress

The following describes the Web API for the Skywire Manager (manager) application. You will need access to a running instance this application in order to utilise the APIs.

Examples provided below assume the Manager is running on the local machine (127.0.0.1). The default port for accessing the API is 8000. All Node and Application keys have been deliberatly altered to ensure they are invalid.

Manager API

The following API services are made avaiable by the Skywire Manager application (manager):

• Manager
  • Login
  • Check Login
  • Change Password
  • Manager Node Request
  • Manager Term
  • Get Manager Port
  • Get Token
• Connections
  • Get All Connections
  • Get Manager Information
  • Get Node Information
  • Set Node Configuration
  • Get Node Configuration
  • Save Client Connection
  • Remove Client Conneciton
  • Edit Client Connection
  • Get Client Connection

Login

Login (authenticate) to the Manager. This is the equivelant of logging into the Manager from the Web UI and is a pre-requisit for a number of other API calls.

Successfuly calling this API will setup an authenticated session with the Manager, and a session cookie will be provided back to the caller as part of the response payload. The session cookie is required as input to a number of other APIs.

The password must be provided as the value for the pass parameter. The following validation is performed on the value provided for pass:

• Not less than 4 or larger than 20 characters. The call will return false if this condition is not met.
• Compares a hashed version of the provided password against the stored password hash. If they are not the same the service will return false.

Usage

URI: /login
Method: Post

Example:

curl -X "POST" "http://127.0.0.1:8000/login" \
     -H 'Content-Type: application/x-www-form-urlencoded; charset=utf-8' \
     --data-urlencode "pass=example-password"

Successful Response:

HTTP/1.1 200 OK
Content-Type: application/json
Set-Cookie: SWSId=1134c7bfcfa34d5c1015dfd473ab0cfa; Path=/; Expires=Wed, 18 Jul 2018 13:44:36 GMT; Max-Age=3600; HttpOnly
Date: Wed, 18 Jul 2018 12:44:36 GMT
Content-Length: 4
Connection: close

true

Error Response:

HTTP/1.1 500 Internal Server Error
Content-Type: text/plain; charset=utf-8
X-Content-Type-Options: nosniff
Date: Wed, 18 Jul 2018 12:42:22 GMT
Content-Length: 22
Connection: close

authentication failed

Check Login

Check Login verifies that the current session is still authorised with the Manager. If an error response is returned, the client must Login again to re-authenticate.

Usage

URI: /checkLogin
Method: Post

Example:

## Manager - checkLogin
curl -X "POST" "http://127.0.0.1:8000/checkLogin" \
     -H 'Content-Type: application/x-www-form-urlencoded; charset=utf-8' \
     -H 'Cookie: SWSId=1134c7bfcfa34d5c1015dfd473ab0cfa'

Successful Response:

HTTP/1.1 200 OK
Content-Type: application/json
Date: Fri, 20 Jul 2018 10:33:22 GMT
Content-Length: 32
Connection: close

6230fa3ce167dc9afcac12fe1a0125fc

Error Response:

HTTP/1.1 302 Found
Content-Type: text/plain; charset=utf-8
Set-Cookie: SWSId=1134c7bfcfa34d5c1015dfd473ab0cfa; Path=/; Expires=Fri, 20 Jul 2018 11:31:43 GMT; Max-Age=3600; HttpOnly
X-Content-Type-Options: nosniff
Date: Fri, 20 Jul 2018 10:31:43 GMT
Content-Length: 18
Connection: close

Unauthorized
false

Update Password

Updates (changes) the Manager password.

Both the old and new passwords must be provided as values for the oldPass and newPass parameters. The following validation is performed on both values, with errors returned of the validation fails:

• Not less than 4 or larger than 20 characters.
• The new password is not the system default password.
• The old (current) password is correct.
• The new password is successfully saved.

Note that the current authenticated session is destroyed when the password is changed. You will need to re-authenticate with the manager using the new password.s

Usage

URI: /updatePass
Method: Post

Example:

curl -X "POST" "http://127.0.0.1:8000/updatePass" \
     -H 'Content-Type: application/x-www-form-urlencoded; charset=utf-8' \
     --data-urlencode "oldPass=oldtest" \
     --data-urlencode "newPass=newtest"

Successful Response:

HTTP/1.1 200 OK
Content-Type: application/json
Set-Cookie: SWSId=; Path=/; Expires=Fri, 20 Jul 2018 11:01:26 GMT; Max-Age=0; HttpOnly
Date: Fri, 20 Jul 2018 11:01:26 GMT
Content-Length: 4
Connection: close

true

Error Response:

HTTP/1.1 200 OK
Content-Type: application/json
Date: Fri, 20 Jul 2018 11:03:07 GMT
Content-Length: 28
Connection: close

New password length is 4~20.

Manager Node Request

Asks the Manager to perform an API request for one of its connected Nodes. Use the /conn/getNode API to obtain the IP and Port for the Node you wish to call an API for.

Note: You must have logged in to the Manager using /login before calling this API.

Set the following parameters on the request:

• addr = URI of the Node API to be called
• method = The HTTP method to be used. This must be either GET or POST (default if not provided)

Usage

URI: /req
Method: Post

Example - Requesting /node/getInfo:

curl -X "POST" "http://127.0.0.1:8000/req" \
     -H 'Content-Type: application/x-www-form-urlencoded; charset=utf-8' \
     -H 'Cookie: SWSId=15723926ac7a3b0d4659cb472ed3cab2' \
     --data-urlencode "addr=http://{IP:PORT}/node/getInfo" \
     --data-urlencode "method=post"

Response:

{"discoveries":{"discovery.skycoin.net:5999-034b1cd4ebad163e457fb805b3ba43779958bba49f2c5e1e8b062482904bacdb68":true},"transports":null,"app_feedbacks":null,"version":"0.1.0","tag":"dev","os":"linux"}

Example - Requesting /node/getApps:

curl -X "POST" "http://127.0.0.1:8000/req" \
     -H 'Content-Type: application/x-www-form-urlencoded; charset=utf-8' \
     -H 'Cookie: SWSId=15723926ac7a3b0d4659cb472ed3cab2' \
     --data-urlencode "addr=http://{IP:PORT}/node/getApps" \
     --data-urlencode "method=post"

Response:

[{"key":"123e56823dc4b83472648172af3936618bca3663a52429fc32afc1870937830496","attributes":["sockss"],"allow_nodes":null}]

Manager Term

Establishes a Terminal session on the Manager Node.

The request requires the following parameters to be provided as URL query strings:

• token - must be a valid token provided by the Manager
• url - provides the request to be performed by the target Node. In this case (Term), it is expected to be in the form ws://127.0.0.1:8000/node/run/term

Once the provided token and url are validated, a WebSocket is established to the remote endpoint provided in the url parameter. The request header is populated with the manager-token.

Usage

URI: /term
Method: Post

Example:

Response:

Get Manager Port

Retreives the Port number that is used by the Manager. The default is 8000.

Usage

URI: /getPort
Method: Get

Example:

curl "http://127.0.0.1:8000/getPort" \
     -H 'Authorization: ' \
     -H 'Cookie: SWSId=bdfbdcda4981101816c1e4b57de1e5de'

Response:

HTTP/1.1 200 OK
Content-Type: application/json
Date: Fri, 20 Jul 2018 11:28:22 GMT
Content-Length: 4
Connection: close

8000

Get Token

Get an API authentication token from the Manager. This is a pre-requisit for calling a number of APIs.

The token returned in the body of the response (as per the example below) is required as a parameter for other API calls.

Usage

URI: /getToken
Method: Get

Example Request:

curl "http://127.0.0.1:8000/getToken"

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json
Date: Wed, 18 Jul 2018 11:53:12 GMT
Content-Length: 64
Connection: close

bf43103c60b1eb30f8cacd619f0b4c7c8feacd6e0fc40ff1c6d3d3573c1d6fd7

Connections

Get All Connections

Get all currently active Node connections from the Manager. There are currently no pre-requisits for calling this API (do not need to be logged in or authenticated).

If the request is successful a JSON array containing zero, one or more Node connections (Conn struct) will be returned. This represents the list of Nodes currently connected to the Manager.

The Conn struct contains the following elements:

• Key (string) - The Node key.
• Type (string) - The connection type. Can be either TCP or UDP.
• SendBytes (unit64) - The number of bytes that have been sent to this node.
• RecvBytes (unit64) - The number of bytes that have been received by this node.
• LastActTime (int64) - The last time the Manager recieved an Acknowledgement from the Node.
• StartTime (int64) - The time the Node was started.

Usage

URI: /conn/getAll
Method: Get

Example Request:

curl "http://127.0.0.1:8000/conn/getAll"

Successful Response:

[
  {
    "key": "01baac57c217b77c70c2c71b78e2445f14a9fc6397341eaab23fec62c6bac42f1c",
    "type": "TCP",
    "send_bytes": 1001,
    "recv_bytes": 1127,
    "last_ack_time": 55,
    "start_time": 4615
  }

  {
    "key": "01bcaf37c253b77c70c2c74a78e2445f14a9ff6397341eaab01fec62c3bfc41a1c",
    "type": "TCP",
    "send_bytes": 100,
    "recv_bytes": 115,
    "last_ack_time": 35,
    "start_time": 4011
  }
]

Error Response:

HTTP/1.1 500 Internal Server Error

Get Manager Information

Get information about the Manager. There are currently no pre-requisits for calling this API (do not need to be logged in or authenticated).

If the request is successful the result provided in the response body is a string composed of the following elements in the following format:

[Host]:[Port]-[Manager Public Key]

Usage

URI: /getServerInfo
Method: Get

Example:

curl "http://127.0.0.1:8000/conn/getServerInfo"

Successful Response:

HTTP/1.1 200 OK
Content-Type: application/json
Date: Wed, 18 Jul 2018 12:14:35 GMT
Content-Length: 81
Connection: close

127.0.0.1:5998-110510c20ac843f63fb1d001b5c1e23b9b46ce6efb9a2c57379f8a67b976af0c11

Error Response:

HTTP/1.1 500 Internal Server Error

Get Node Information

Get detailed information from the Manager about the specified Node. The Node Key must be passed as a query string to the key parameter on the URI.

Use the /conn/getAll to obtain a list of the connect Node keys, then use one of the returned Node Keys as input to this API request.

This API will provide the IP:PORT of the Node. This information will be required to make API requests to the Node using the /req API.

Note: You must have already logged into the Manager using the /login API.

Usage

URI: /conn/getNode?key={node=key}
Method: Post

Example:

curl -X "POST" "http://127.0.0.1:8000/conn/getNode?key=06bfac57c217b77c70c2c71b78e2445f14a9fc6397341eaab23fec62c6bac42c1c" \
     -H 'Cookie: SWSId=aeecf9e41466555a16f9a5891e084eb6'

Response:

{"type":"TCP","addr":"127.0.0.1:6001","send_bytes":322,"recv_bytes":455,"last_ack_time":22,"start_time":82}

Set Node Configuration

Usage

URI: /conn/setNodeConfig
Method: POST

Example:

Response:

Get Node Configuration

Get the configuration of a specified Node. The following form values are expected:

• key - the key of the Node the request is being made for.

This operation is performed locally on the Manager. A Mutex is obtained to lock the configuration file before reading. The Manager will perform a look-up of the provided Node key in the config file and return a JSON structure contianing the configuraiton if found. If not found the response will be no found

Usage

URI: /conn/getNodeConfig
Method: POST

Example (Incomplete):

curl -X "POST" "http://127.0.0.1:8888/term?url=ws://192.168.0.101:6001/node/run/term&token=889cc2bd9590dc94aa1e772c84fade844e58e01f092a60376b6af2c6e5fb16c6"

500 (Not Found) Response:

HTTP/1.1 500 Internal Server Error
Content-Type: text/plain; charset=utf-8
X-Content-Type-Options: nosniff
Date: Sun, 14 Oct 2018 20:41:35 GMT
Content-Length: 9
Connection: close

no found

302 (Unauthorised) Response:

HTTP/1.1 302 Found
Content-Type: text/plain; charset=utf-8
X-Content-Type-Options: nosniff
Date: Mon, 15 Oct 2018 19:17:09 GMT
Content-Length: 13
Connection: close

Unauthorized

Save Client Connection

Note: You must have already logged into the Manager using the /login API.

The request must contain the following data in the body of the form that is posted:

• data - this is a JSON structure representing the Client configuration to be saved and is expected to be of type ClientConnection.
• client - is the Node Key (TBC)

Usage

URI: /conn/saveClientConnection
Method: POST

Example:

Response:

Remove Client Connections

Usage

URI: /conn/removeClientConnections
Method: TBA

Example:

Response:

Edit Client Connection

Edits information about the specified client connection.

The following parameters must be passed as form data:

• client - The client (Node Key) that the configuration is being requested for. TODO: Need to verify this is the Node Key.
• label - The new label for the Node
• index - The new Index (TODO: not sure what this is) for the Node.

Note: You must have already logged into the Manager using the /login API.

Usage

URI: /conn/editClientConnection
Method: POST

Example:

curl -X "POST" "http://127.0.0.1:8000/conn/editClientConnection" \
     -H 'Content-Type: application/x-www-form-urlencoded; charset=utf-8' \
     -H 'Cookie: SWSId=46b173f2035a87ff42ee905e8b9533d8' \
     --data-urlencode "client=06bfac57c217b77c70c2c71b78e2445f14a9fc6397341eaab23fec62c6bac42c1c" \
     --data-urlencode "label=Node1" \
     --data-urlencode "index=1"

Response:

Get Client Connection

Retrieves information about the specified client connection from the Manager.

The following parameters must be passed as form data:

• client - The client (Node Key) that the configuration is being requested for. TODO: Need to verify that this is the Node Key.

Note: You must have already logged into the Manager using the /login API.

Usage

URI: /conn/getClientConnection
Method: GET

Example:

curl -X "POST" "http://127.0.0.1:8888/conn/getClientConnection" \
     -H 'Content-Type: application/x-www-form-urlencoded; charset=utf-8' \
     -H 'Cookie: SWSId=ec2c446717fefeba98a2ab791bcea66c' \
     --data-urlencode "client=t06bfac57c217b77c70c2c71b78e2445f14a9fc6397341eaab23fec62c6bac42c1ccp"

Response:

HTTP/1.1 200 OK
Content-Type: application/json
Date: Sun, 14 Oct 2018 20:37:47 GMT
Content-Length: 4
Connection: close

null