TermFTP-API

The backend (server) for TermFTP built with Java

Endpoints

The general request path is as follows: <ip>:<port>/api/v1

Endpoints

POST: api/v1/register
POST: api/v1/login
POST: api/v1/createServer
GET: api/v1/serverGroups
POST: api/v1/group
PUT: api/v1/updateServer
DELETE: api/v1/removeServerFromGroup
DELETE: api/v1/removeGroup
DELETE: api/v1/removeServer
GET: api/v1/confirm-account
DELETE: api/v1/deleteUser
POST: api/v1/connection
GET: api/v1/connections
GET: api/v1/settings
POST: api/v1/settings
DELETE: api/v1/deleteSettings

Register

This endpoint is used to create a new user (register). Hereby, a verification email will be sent to the users email address. As soon as the user opens the link, the field verified changes to true.

URI: api/v1/register
Type: POST

Body: a simplified version of the User object

{
    "username" : "user1",
    "password" : "a_pw",
    "email" : "[email protected]"
}

Note: email must be unique!

Response-Body: DefaulRespone with the newly created user

{
    "status": 200,
    "message": "Created User",
    "data": {
        "username": "user1",
        "email": "[email protected]",
        "userID": "6293eed0-cbb7-4d7b-97df-49f45dc98528",
        "verified": false
    }
}

Login

This endpoint is used to login a user. After a successful login, this endpoint returns a unique Access-Token that required for many other endpoints.

URI: api/v1/login
Type: POST
Headers:
- PC-Name : the-name-of-someones-pc

Body

{
    "username" : "user1",
    "password" : "a_pw"
}

Response-Body: DefaulRespone with the latest Access-Token

{
    "status": 200,
    "message": "AccessToken",
    "data": {
        "accessTokenID": {
            "token": "pzklzntrphjrabczvbxilzhoitggyaqi",
            "userID": "6293eed0-cbb7-4d7b-97df-49f45dc98528"
        },
        "validUntil": "2021-04-02",
        "pcName": "morpheus"
    }
}

Create Server

This endpoint is used to create a single server.

URI: api/v1/createServer
Type: POST
Headers:
- Access-Token : <access-token>

Body

{
    "ip" : "127.0.0.3",
    "ftpPort" : "21",
    "sshPort" : "22",
    "name" : "local2",
    "username" : "admin",
    "password" : "admin"
}

Response-Body: DefaulRespone with the created Server

{
    "status": 200,
    "message": "Created Server",
    "data": {
        "serverID": "39957cfc-54e9-4347-939f-c976df1ff289",
        "ip": "127.0.0.3",
        "ftpPort": 21,
        "sshPort": 22,
        "lastConnection": null,
        "name": "local2",
        "username": "admin",
        "password": "admin"
    }
}

Server Groups

This endpoint is used to retrieve the whole tree of server groups (and sub-groups) with the containing servers PER USER.

URI: api/v1/serverGroups
Type: GET
Headers:
- Access-Token : <access-token>

Response-Body: DefaulRespone with the tree of ServerGroups (list)

{
    "status": 200,
    "message": "Server-Groups",
    "data": [
        {
            "groupID": "839fad77-e6e5-4751-a6a2-803ca56f61af",
            "name": "default",
            "userID": "6293eed0-cbb7-4d7b-97df-49f45dc98528",
            "serverGroups": [],
            "server": [
                {
                    "serverID": "39957cfc-54e9-4347-939f-c976df1ff289",
                    "ip": "127.0.0.3",
                    "ftpPort": 21,
                    "sshPort": 22,
                    "lastConnection": null,
                    "name": "local2",
                    "username": "admin",
                    "password": "admin"
                }
            ]
        },
        {
            "groupID": "e1e81224-c73e-4e68-933e-657368f6f2d8",
            "name": "favourites",
            "userID": "6293eed0-cbb7-4d7b-97df-49f45dc98528",
            "serverGroups": [],
            "server": []
        }
    ]
}

Group Servers

This endpoint is used to create or change server groups. You can either create empty groups, sub-groups or groups with servers. Additionally this endpoints lets you change the name of the group or add further servers to it.

URI: api/v1/group
Type: POST
Headers:
- Access-Token : <access-token>

Body

Create an empty group
- Note: When creating a new group, don't send any groupID (otherwise the existing group with that ID will be renamed)
```
{
    "groupID" : null,
    "name" : "empty-group-01",
    "groups" : null,
    "servers" : null
}
```
Add a sub-group
- Important
  - The sub group needs to be created first
  - The ID of the sub-group must not be the same as the parent groupID
- groupID ... parent group
- groups ... an array of sub-groups (which must already exist)
```
{
    "groupID" : "363855af-7aca-4ab0-951b-6411a0c345b6",
    "name" : null,
    "groups" : ["987855af-kd8454ab0-851c-7511a1c375c8"],
    "servers" : null
}
```

Create a group with servers in it

Note: When creating a new group, don't send any groupID (otherwise the existing group with that ID will be renamed)

{
    "groupID" : null,
    "name" : "work",
    "groups" : null,
    "servers" : ["39957cfc-54e9-4347-939f-c976df1ff289"]
}

Rename a group

Note: When renaming a group, both the groupID and the name must be given

{
    "groupID" : "39957cfc-54e9-4347-939f-c976df1ff289",
    "name" : "work",
    "groups" : null,
    "servers" : ["39957cfc-54e9-4347-939f-c976df1ff289"]
}

Response-Body: DefaulRespone with the created/changed ServerGroup

{
    "status": 200,
    "message": "Server-Group",
    "data": {
        "groupID": "363855af-7aca-4ab0-951b-6411a0c345b6",
        "name": "work",
        "userID": "6293eed0-cbb7-4d7b-97df-49f45dc98528",
        "serverGroups": [],
        "server": [
            {
                "serverID": "39957cfc-54e9-4347-939f-c976df1ff289",
                "ip": "127.0.0.3",
                "ftpPort": 21,
                "sshPort": 22,
                "lastConnection": null,
                "name": "local2",
                "username": "admin",
                "password": "admin"
            }
        ]
    }
}

this is a response of Create a group with servers in it

Update Server

This endpoint is used to update a single server.

URI: api/v1/updateServer
Type: PUT
Headers:
- Access-Token : <access-token>

Body: the updated Server object

{
    "serverID" : "39957cfc-54e9-4347-939f-c976df1ff289",
    "ip" : "127.0.0.11",
    "ftpPort" : 21,
    "sshPort" : 22,
    "username" : "admin",
    "password" : "nowthereisastrongerpw"
}

Response-Body: DefaulRespone with the updated Server

{
    "status": 200,
    "message": "Updated Server",
    "data": {
        "serverID": "39957cfc-54e9-4347-939f-c976df1ff289",
        "ip": "127.0.0.11",
        "ftpPort": 21,
        "sshPort": 22,
        "lastConnection": null,
        "name": null,
        "username": "admin",
        "password": "nowthereisastrongerpw"
    }
}