apiary.apib

# SHM v1 API
FORMAT: 1A

## About SHM

TODO

## API Requests

TODO
## Modify Login form

TODO

## Return codes

HTTP 401, 403, 500, 
503 - Restart in progress
TODO

## Your own theme recomendations

Our theme is free under GNU license, you can modify and use them at your own themes.
We used AngularJS and Bootstrap for them.

For using your own theme just upload theme files to `html/MyOwnTheme` folder inside panel homedir and
add theme name to main config `etc/main.conf` at `[Core]` section to `Themes`.
First theme in the list will be default theme for all users. Default language is `EN`.

For example: 
```
[Core]
Themes = ["MyOwnTheme", "Simple"]
```
Service restart needed to reload config.




# Data Structures

## Error (object)
+ error (required,object)

## Files (object)
+ Dir (required, boolean) - Is dir.
+ Name (required, string) - Name of the dir or file.
+ Size (required, number) - Size in bytes.
+ Permissions (required, number) - Permissions.
+ Owner (required, number) - Owner of file or dir.
+ Group (required, number) - Group of file or dir.
+ Modified (required, string) - Date time of last modification.




# Group Remove testing user regularUser

## #AuthRoot for testing user removing [POST /login]

+ Request (application/json)
        {
            "Login": "root",
            "Password": "$ROOT_PASSWORD"
        }

+ Response 200 (application/json)
        {
            "Auth": "Logged",
            "Theme": "Simple",
            "Language": "EN"
        }


## Removing testing user regularUser [POST /api/users/del]

+ Request (application/json)
        {  
            "Name":"$USER_NAME"
        }

+ Response 204 (text/plain)

## Logout from Root [GET /logout]

+ Response 204 (text/plain)




# Group Create regularUser for tests

## #AuthRoot for testing user creation [POST /login]

+ Request (application/json)
        {
            "Login": "root",
            "Password": "$ROOT_PASSWORD"
        }

+ Response 200 (application/json)
        {
            "Auth": "Logged",
            "Theme": "Simple",
            "Language": "EN"
        }

## Create testing user regularUser [POST /api/users/set]

+ Request (application/json)
        {  
            "Username":"$USER_NAME",
            "Password":"$USER_PASSWORD",
            "Info":{  
                "Active":true,
                "Comment":"Just a testing user",
                "Template":"SimpleUser",
                "Email":"root@localhost",
                "Theme":"Alpha",
                "Language":"EN",
                "HOTP":{  
                    "Active":false
                }
            }
        }

+ Response 204 (text/plain)

## Logout from Root [GET /logout]

+ Response 204 (text/plain)




# Group Panel Authorization

First of all you must login into panel as `root` to gain administrator privileges or as a regular user.
For login you must use your credentials of user or root login and password if you are the server administrator.




## User login [/login]
For login you must use your credentials of a user that was registered by the `root` in a panel.

+ Attributes
    + Login (required,string) - User's login, which is email or root for admin.
    + Password (required,string) - User defined password or root password for admin.
    + Hotp (optional, string) - Code from two step authorization app.
    + Auth (string) - Authorization status.

### Login fails [POST]
If login and password is not correct you will receive `403 Forbidden`. 
Debug information about login, user not found or wrong password are in the system's log file.

+ Request (application/json)
        {
        "Login": "$USER_NAME",
        "Password": "wrongUserPassword"
        }

+ Response 403 (application/json)
        {
            "Auth": "Denied"
        }

### Login success #AuthUser [POST]
If login and(or) password is correct you will receive success login response with
`Theme` is a GUI theme, `Language` is a user defined interface language.
Login script do redirect to `https://server:port/Theme` to load GUI for theme.


+ Attributes
    + Theme:Simple (required, string) - User defined GUI theme.
    + Language:EN (required, string) - User defined language for GUI.

+ Request (application/json)
        {
            "Login": "$USER_NAME",
            "Password": "$USER_PASSWORD"
        }

+ Response 200 (application/json)
        {
            "Auth": "Logged",
            "Theme": "Simple",
            "Language": "EN"
        }




### HOTP code required [POST]

How to [turn on two step authorization](two-step-authorization)
If user turned on two step authorization from Google Authenticator or other HOTP compatible mobile app, 
HOTP code must be present along with login and password fields.
You need to repeat login request with HOTP code from user's mobile app.

+ Request (application/json)
        {
            "Login": "hotpUser",
            "Password": "hotpUserSecretPassword"
        }

+ Response 449 (application/json)
        {
            "Auth": "HOTP required"
        }
 
### Login with HOTP success [POST]

If HOTP code from user's app correct, you'll receive `200` and `Login success` reply.

+ Attributes
    + HOTP (required, string) - Code from device for two step authorization.

+ Request (application/json)
        {
            "Login": "hotpUser",
            "Password": "hotpUserSecretPassword",
            "Hotp":"12345"
        }

+ Response 200 (application/json)
        {
            "Auth": "Logged",
            "Theme": "Simple",
            "Language": "EN"
        }


### Login fails because HOTP wrong code [POST]
In case of wrong HOTP code `403` would be received. 
You can send another request with correct HOTP code.

+ Request (application/json)
        {
            "Login": "hotpUser",
            "Password": "hotpUserSecretPassword",
            "Hotp":"54321"
        }

+ Response 403 (application/json)
        {
            "Auth": "HOTP wrong code"
        }




## Root login [/login]
For login you must use your root system password and login `root`.

### Root login fails [POST]
If password is not correct you will receive `403 Forbidden`. 

+ Request (application/json)
        {
        "Login": "root",
        "Password": "wrongPassword"
        }

+ Response 403 (application/json)
        {
            "Auth": "Denied"
        }

### Root login success #AuthRoot [POST]

+ Attributes
    + Theme:Simple (required, string) - User defined GUI theme.
    + Language:EN (required, string) - User defined language for GUI.

+ Request (application/json)
        {
            "Login": "root",
            "Password": "$ROOT_PASSWORD"
        }

+ Response 200 (application/json)
        {
            "Auth": "Logged",
            "Theme": "Simple",
            "Language": "EN"
        }




# Group Create Test environment
Creating test environment.

## Add MySQL test user as #User [POST /api/mysql/users/set]
Add test user for PgSQL dumps.

+ Request (application/json)
        {  
        "Username":"DBUser1",
        "Password":"NewMyDBUserPassword",
        "Host":"localhost"
        }

+ Response 204 (text/plain)

## Add PgSQL test user as #User [POST /api/pgsql/users/set]
Add test user for PgSQL dumps.

+ Request (application/json)
        {  
            "Username":"DbTester",
            "Password":"NewMyDBTesterPassword"
        }

+ Response 204 (text/plain)

## Add PGSQL db for Import as #User [POST /api/pgsql/db/set]

+ Request (application/json)
        {  
            "DbName":"DbImport",
            "DbUser":"DbTester"
        }

+ Response 204 (text/plain)

## Create test.html file by Root [POST /api/filemanager/editfile]
Create /var/www/test.html by Root.

+ Request (application/json)
        {
            "Filename": "/var/www/test.html",
            "Encoding": "ISO 8859-2",
            "Text":"<h1>Hello world!</h1>"
        }

+ Response 204 (text/plain)

## Create /test.html file by #User [POST /api/filemanager/editfile]
Create /home/USER/test.html by User.

+ Request (application/json)
        {
            "Filename": "/test.html",
            "Encoding": "ISO 8859-2",
            "Text":"<h1>Hello world!</h1>"
        }

+ Response 204 (text/plain)

## Create from_root.html in user's dir by Root [POST /api/filemanager/editfile]

+ Request (application/json)
        {
            "Filename": "/home/regularUser/from_root.html",
            "Encoding": "ISO 8859-2",
            "Text":"<h3>Created by root!</h3>"
        }

+ Response 204 (text/plain)

## Create dirs for TAR archive testing as Root [POST /api/filemanager/mkdir]

+ Request (application/json)
        {
            "Dir":   "/var/www",
            "Mkdir": "test_archives/tar"
        }

+ Response 204 (text/plain)

## Create dirs for ZIP archive testing as Root [POST /api/filemanager/mkdir]

+ Request (application/json)
        {
            "Dir":   "/var/www",
            "Mkdir": "test_archives/zip"
        }

+ Response 204 (text/plain)

## Create dir for TAR archive testing as #User [POST /api/filemanager/mkdir]

+ Request (application/json)
        {
            "Dir":   "/www",
            "Mkdir": "test_archives/tar"
        }

+ Response 204 (text/plain)

## Add test.com domain as #User [POST /api/webdomains/set]

+ Request (application/json)
        {  
                "Name":"$TESTING_DOMAIN",
                "Active":true,
                "Alias":"www.$TESTING_DOMAIN site.$TESTING_DOMAIN",
                "Ip":"$SERVER_IP",
                "IndexFile":"index.html",
                "Encoding":"utf8",
                "Subdomains":true,
                "PHP":"fpm_nginx",
                "DNS":true,
                "SSL":false,
                "Analytics":true
        }

+ Response 204 (text/plain)

## Add info@test.com Email box as #User [POST /api/email/set]

+ Request (application/json)
    {  
       "Email":"info@$TESTING_DOMAIN",
       "Alias":"",
       "Size":500,
       "Password":"infoPassword"
    }

+ Response 204 (text/plain)

## Generate DKIM record for info@test.com as #User [POST /api/dkim/set]

+ Request (application/json)
    {  
       "Domain":"$TESTING_DOMAIN"
    }

+ Response 204 (text/plain)




# Group Two step authorization

For using two step authorization you can install **Google Authenticator** or other mobile app that support HOTP protocol.
There are two ways to add your app for two step authorization:
* Enter generated code at your mobile Google Authenticator app,
* Scan generated QR code on your mobile Google Authenticator app,

For proper QR generation you need to get code first and only after that make request to generate QR.




## Generate code for enter by hand [/api/hotp/code]

This request will generate one time code that you need to enter while add new account to Google Authenticator app.

### Getting key code [GET]
Generate one time key code.

+ Attributes
    + Key (required,string) - One time generated key for app binding.

+ Response 200 (application/json)
        {
            "Key": "12368615794617"
        }

## Generate QR [/api/hotp/qr]

This request will generate one time code that you need to save in your Google Authenticator app.

### Getting QR image with code [GET]
Generate PNG image with QR code you can scan by Google Authenticator to add account.

+ Response 200 (image/jpeg)
          

## Check for correct app binding [/api/hotp/check]

Before two step authorization cat be enabled we need to check if everything is good. 
You need to enter first generated code from your app.

### HOTP app Code correct [POST]

+ Request (application/json)
        {
            "Confirm": "95726283"
        }

+ Response 204 (text/plain)

### HOTP app Wrong code [POST]
If app was not binded properly, first code was not accepted.

+ Request (application/json)
        {
            "Confirm": "7324545"
        }

+ Response 406 (text/plain)

## HOTP toggle [/api/hotp/toggle]

!TODO





# Group FTP accounts
PFTPD server accounts.




## Add or Edit FTP account [POST /api/pftpd/set]

Add or edit FTP accounts.

+ Attributes
  + UserID (required, string) - FTP account login name.
  + Password (required, string) - FTP account password.
  + User (optional, string) - Panel user which owns FTP account. Only `root` can set User.
  + Homedir (required, string) - FTP directory path related to current user's homedir.

+ Request (application/json)
    {
        "UserID":     "FTP1",
        "Password" : "FTPPassword",
        "Homedir":       "/www/$TESTING_DOMAIN/"
        }

+ Response 204 (text/plain)

## List FTP accounts [GET /api/pftpd/list]

List all user's FTP account.

+ Response 200 (application/json)
    [
        {  
       "UserID":"$USER_NAME_FTP1",
           "Homedir":  "/www/$TESTING_DOMAIN/"
        }
    ]

## !Hook FTP account testing [GET /hook]

Test FTP account by ftp client

+ Response 299

## Remove FTP accounts [POST /api/pftpd/del]

Remove FTP accounts.

+ Request (application/json)
    ["FTP1"]

+ Response 204 (text/plain)

## Remove non existent ftp account #Error [POST /api/pftpd/del]

+ Request (application/json)
    ["FTPNotExist"]

+ Response




# Group Remove Test environment
Remove test environment.

## Remove dirs for ZIP archive testing as Root [POST /api/filemanager/del]

+ Request (application/json)
        [
            "/var/www/test_archives/zip"
        ]

+ Response 204 (text/plain)

## Remove dirs for TAR archive testing as Root [POST /api/filemanager/del]

+ Request (application/json)
        [
            "/var/www/test_archives/tar"
        ]

+ Response 204 (text/plain)




# Group Logout

To close current session user can logout by request. This is not necessary but recommended to close the session.
If user is inactive for 1800 seconds, session will be destroyed by the panel itself. 
You can change this value in config file at `GHttp.SessionLifeTime`.

## #User logout [GET /logout]
Close the regular user session.

+ Response 204 (text/plain)

## Root logout [GET /logout]
Administrator `root` session close.

+ Response 204 (text/plain)