API

Prerequisites

• Have the server running.
• To request a file explorer you can use any programming language that can send an HTTP request.
  • For the examples, Python with requests will be used.

How to request a file explorer

1. Prepare the credentials for the SFTP connection

You must have:

• name (a display name for the connection, only shows in the browser tab)
• hostname
• port (if not provided, it is 22)
• username
• password or ssh_key (the SSH key will take priority)
• path (the initial directory path, default /)

Warning

The SSH Key must be sent as a string and must have the \n like the standard keys.

data = {
  "name": "My SFTP",
  "host": "sftp.example.com",
  "port": 22,
  "username": "user",
  "password": "mypassword", # If you have to use the SSH key, omit this
  "privateKey": "", 
  "path": "/"
}

2. Make the request to save the credentials in the server

Send a request to the POST /api/sftp/credentials/create endpoint with the credentials prepared before in the JSON body.

import requests
server_url = "http://127.0.0.1:3000"
endpoint = "/api/sftp/credentials/create"

# Request with password
response1 = requests.post(server_url+endpoint, data=data)

You will obtain a JSON containing a connection_uuid. On error, you’ll receive an error message and appropriate HTTP status.

Example response:

{
  "connection_uuid": "generated-uuid"
}

Credential creation diagram

sequenceDiagram
    participant U as User
    participant S as Server

    U->>S: HTTP POST /api/sftp/credentials/create (credentials)
    S->>S: Generate UUID
    S->>S: Save credentials with key UUID
    S-->>U: JSON {UUID}

Loading

3. Make the request to obtain the file explorer

First, create credentials as above and get the connection_uuid.

Then, make a request to the GET /?connection=<connection_uuid> endpoint, by replacing <connection_uuid> with the UUID you received.

This will return an HTML page already connected to this server and the remote SSH server.

connection_uuid = response1['connection_uuid']
url = f'http://127.0.0.1:5000/?connection={connection_uuid}'
response2 = requests.get(url)

You can also use a URL to make the request in your browser.

http://127.0.0.1:3000/?connection=<connection_uuid>

Note

It even works in an <iframe> HTML tag.

<iframe src="url" width="800" height="600"></iframe>

Credential retrieval and connection diagram

sequenceDiagram
    participant User
    participant WebClient
    participant Server

    User->>WebClient: HTTP POST /?connection=uuid
    WebClient->>Server: GET /api/sftp/credentials/:key
    Server-->>WebClient: { success, credentials }
    WebClient->>Server: GET /api/sftp/files/stat (for initial path)
    Server-->>WebClient: { stats }
    WebClient->>Server: GET /api/sftp/directories/list
    Server-->>WebClient: { list }
    WebClient-->>User: Show file explorer UI

Loading