System API

System API allows to perform some system wide operations

  1. Base URI
  2. Packages manager APIs
  3. Setting manager API
  4. API Gateway

1. Base URI

All URI to the system API should start with /system

Request

GET /system HTTP/1.1

Description & response

This operation return the API description in JSON format as follow:

{
    "error": false,
    "result": {
        "description": "This api handle system operations",
        "actions": {
            "/apigateway": "Gateway for executing custom server side code",
            "/settings": "Save user setting",
            "/packages": "Handle all operation relate to package: list, install, cache, uninstall"
        }
    }
}

2. Packages manager APIs

All system calls to the packages manager API is perform via the following URI

/system/packages

Package manager performs only two simple operations list and cache. Install/uninstall a package can be performed using the VFS API.

There are two types of packages in AntOS:

  • System packages: these packages are included by default in any AntOS system and are available to all users in the system. They cannot be uninstalled by a normal user. Usually, these packages are store in os://packages/ (VFS path, refer to the VFS section to know about the format)
  • User-specific packages: these packages are installed locally on the user's home directory, and are available only to that user. By default these packages are stored in home://.packages, but this VFS path can be configured by each user.

List all packages

This operation list all packages available in the provided paths, usually these paths are the paths to the system packages and user-specific packages.

This operation looks for the packages.json in each provided paths. This file contains the cache of all packages in that location generated by the cache operation.

Request

POST /system/packages HTTP/1.1
Content-Type: application/json

{
    "command": "list",
    "args": {
        "paths": [
            "os://packages",
            "home://.packages"
        ]
    }
}

Response

On success, the response should return JSON data with something similar to the following snippet:

{
    "result": {
        "MarketPlace": {
            "locales": [],
            "version": "0.0.1-a",
            "iconclass": "fa fa-adn",
            "category": "System",
            "path": "os://packages/MarketPlace",
            "mimes": ["none"],
            "description": "Application store",
            "name": "Application store",
            "app": "MarketPlace",
            "info": {
                "email": "xsang.le@gmail.com",
                "author": "Xuan Sang LE"
            }
        },
        "Syslog": {
            "version": "0.0.1-a",
            "iconclass": "fa fa-bug",
            "category": "System",
            "pkgname": "Syslog",
            "mimes": [],
            "path": "os://packages/Syslog",
            "app": "Syslog",
            "description": "Core services and system log",
            "name": "System log",
            "services": ["Calendar", "PushNotification"],
            "info": {
                "licences": "GPLv3",
                "credit": "dedicated to some one here",
                "email": "xsang.le@gmail.com",
                "author": "Xuan Sang LE"
            }
        },
        "Files": {
            "locales": [],
            "version": "0.0.3-a",
            "iconclass": "fa fa-hdd-o",
            "category": "System",
            "path": "os://packages/Files",
            "mimes": ["dir"],
            "description": "System files manager",
            "name": "Files manager",
            "app": "Files",
            "info": {
                "email": "xsang.le@gmail.com",
                "author": "Xuan Sang LE"
            }
        },
        "CodePad": {
            "version": "0.0.2-a",
            "iconclass": "fa fa-pencil-square-o",
            "category": "Developments",
            "path": "os://packages/CodePad",
            "mimes": ["text/.*", "[^/]*/json.*", "[^/]*/.*ml", "[^/]*/javascript", "dir"],
            "description": "Code editor",
            "name": "Code",
            "app": "CodePad",
            "info": {
                "licences": "GPLv3",
                "email": "xsang.le@gmail.com",
                "author": "Xuan Sang LE"
            }
        },
        "Setting": {
            "version": "0.0.1-a",
            "iconclass": "fa fa-wrench",
            "category": "System",
            "path": "os://packages/Setting",
            "mimes": ["none"],
            "description": "System setting",
            "name": "System setting",
            "app": "Setting",
            "info": {
                "email": "xsang.le@gmail.com",
                "author": "Xuan Sang LE"
            }
        },
        "About": {
            "locales": {
                "fr_FR": {
                    "About AntOS": "A propos d'AntOS",
                    "Unable to read: {0}": "Impossible de lire: {0}"
                }
            },
            "version": "0.0.5-a",
            "iconclass": "fa fa-question-circle",
            "category": "Other",
            "path": "home://.packages/About",
            "mimes": ["none"],
            "description": "AntOS about",
            "name": "About AntOS",
            "app": "About",
            "info": {
                "email": "xsang.le@gmail.com",
                "author": "Xuan Sang LE"
            }
        }
    },
    "error": false
}

Cache packages

Generate cache file (packages.json) of all packages on the provided packages paths. For each path, the operation looks for all packages, reads their meta-data and create the cache file. One cache file is generated for each path.

Request

POST /system/packages HTTP/1.1
Content-Type: application/json

{
    "command": "cache",
    "args": {
        "paths": [
            "os://packages",
            "home://.packages"
        ]
    }
}

Response

On success the response should be:

{"result":true,"error":false}

3. Setting manager API

The setting manager API contains only one operation: save the current user setting. User setting is stored in home://.setting.json and is read on the beginning of a user session (after login). Any change on the user setting should be saved using this API. This action is performed automatically on user logged out or manually by applications.

Request

POST /system/settings HTTP/1.1
Content-Type: application/json

{
    "applications": {
        "MarketPlace": [],
        "CodePad": [],
        "Syslog": [],
        "About": [],
        "Files": {
            "showhidden": false,
            "nav": true,
            "sidebar": true
        },
        "Setting": []
    },
    "desktop": {
        "menu": [],
        "path": "home://.desktop",
        "showhidden": false
    },
    "user": {
        "username": "demo",
        "groups": {
            "0": "root",
            "27": "sudo",
            "110": "lxd",
            "1002": "demo"
        },
        "name": "demo",
        "id": 1002
    },
    "appearance": {
        "theme": "antos_dark",
        "wp": {
            "repeat": "repeat",
            "url": "os://resources/themes/system/wp/wp3.jpg",
            "size": "cover"
        },
        "wps": [],
        "themes": [
            {
                "text": "AntOS light",
                "name": "antos_light",
                "selected": false
            },
            {
                "text": "AntOS dark",
                "name": "antos_dark",
                "selected": true
            }
        ]
    },
    "VFS": {
        "mountpoints": [
            {
                "iconclass": "fa  fa-adn",
                "path": "app://",
                "type": "app",
                "text": "__(Applications)"
            },
            {
                "iconclass": "fa fa-home",
                "path": "home://",
                "selected": true,
                "type": "fs",
                "text": "__(Home)"
            },
            {
                "iconclass": "fa fa-desktop",
                "path": "home://.desktop",
                "selected": false,
                "type": "fs",
                "text": "__(Desktop)"
            },
            {
                "iconclass": "fa fa-inbox",
                "path": "os://",
                "selected": false,
                "type": "fs",
                "text": "__(OS)"
            },
            {
                "iconclass": "fa fa-share-square",
                "path": "shared://",
                "type": "fs",
                "text": "__(Shared)"
            }
        ]
    },
    "system": {
        "packages": {
            "MarketPlace": {
                "locales": [],
                "version": "0.0.1-a",
                "iconclass": "fa fa-adn",
                "category": "System",
                "path": "os://packages/MarketPlace",
                "mimes": [
                    "none"
                ],
                "description": "Application store",
                "name": "Application store",
                "app": "MarketPlace",
                "info": {
                    "email": "xsang.le@gmail.com",
                    "author": "Xuan Sang LE"
                },
                "text": "Application store",
                "filename": "MarketPlace",
                "type": "app",
                "mime": "antos/app"
            },
            "Syslog": {
                "version": "0.0.1-a",
                "iconclass": "fa fa-bug",
                "category": "System",
                "pkgname": "Syslog",
                "mimes": [],
                "path": "os://packages/Syslog",
                "app": "Syslog",
                "description": "Core services and system log",
                "name": "System log",
                "services": [
                    "Calendar",
                    "PushNotification"
                ],
                "info": {
                    "licences": "GPLv3",
                    "credit": "dedicated to some one here",
                    "email": "xsang.le@gmail.com",
                    "author": "Xuan Sang LE"
                },
                "text": "System log",
                "filename": "Syslog",
                "type": "app",
                "mime": "antos/app"
            },
            "Files": {
                "locales": [],
                "version": "0.0.3-a",
                "iconclass": "fa fa-hdd-o",
                "category": "System",
                "path": "os://packages/Files",
                "mimes": [
                    "dir"
                ],
                "description": "System files manager",
                "name": "Files manager",
                "app": "Files",
                "info": {
                    "email": "xsang.le@gmail.com",
                    "author": "Xuan Sang LE"
                },
                "text": "Files manager",
                "filename": "Files",
                "type": "app",
                "mime": "antos/app"
            },
            "CodePad": {
                "version": "0.0.2-a",
                "iconclass": "fa fa-pencil-square-o",
                "category": "Developments",
                "path": "os://packages/CodePad",
                "mimes": [
                    "text/.*",
                    "[^/]*/json.*",
                    "[^/]*/.*ml",
                    "[^/]*/javascript",
                    "dir"
                ],
                "description": "Code editor",
                "name": "Code",
                "app": "CodePad",
                "info": {
                    "licences": "GPLv3",
                    "email": "xsang.le@gmail.com",
                    "author": "Xuan Sang LE"
                },
                "text": "Code",
                "filename": "CodePad",
                "type": "app",
                "mime": "antos/app"
            },
            "Setting": {
                "version": "0.0.1-a",
                "iconclass": "fa fa-wrench",
                "category": "System",
                "path": "os://packages/Setting",
                "mimes": [
                    "none"
                ],
                "description": "System setting",
                "name": "System setting",
                "app": "Setting",
                "info": {
                    "email": "xsang.le@gmail.com",
                    "author": "Xuan Sang LE"
                },
                "text": "System setting",
                "filename": "Setting",
                "type": "app",
                "mime": "antos/app",
                "selected": false
            }
        },
        "pkgpaths": {
            "system": "os://packages",
            "user": "home://.packages"
        },
        "repositories": [
            {
                "text": "AntOS Github Repository",
                "selected": false,
                "url": "https://raw.githubusercontent.com/lxsang/antosdk-apps/master/packages.json"
            }
        ],
        "menu": [],
        "startup": {
            "services": [
                "Syslog/PushNotification",
                "Syslog/Calendar"
            ],
            "apps": []
        },
        "locale": "en_GB",
        "error_report": "https://os.iohub.dev/report"
    }
}

Detail on the system setting object format can be found on the client API documentation

Response

On success the response should be:

{"result":true,"error":false}

4. API Gateway

An apigateway allows client side to execute a custom server-side script and get back the result. This gateway is particularly useful in case of performing a task that is not provided by the core API.

Base URI: /system/apigateway

For security reason, before executing any server-side script using this API gateway, if the server is run on behalf of a user (such as root) other than the request's user, the server user privileges should be dropped to the request's user privileges.

The server side API gateway should provide two modes of operation:

single round-trip gateway

This mode of operation requests the server to execute a server side script file or snippet, wait for the execution to finish then read back the response.

This mode is suitable for simple operation that does not take too much time to finish

Request

POST /system/apigateway HTTP/1.1
Content-Type: application/json

{
    "path": [VFS path to the server side script],
     "parameters": [parameters of the server-side script]
}

or

POST /system/apigateway HTTP/1.1
Content-Type: application/json

{
    "code": [server side code snippet to be executed]
}

Response

On success, the operation returns the response of the execution in any format

Streaming gateway

The streaming mode is suitable for data streaming during the execution of the custom server side script. In this mode, the client-server connection is established using a web-socket connection.

A the beginning, the client open a web socket connection to the gateway using the base uri (i.e. /system/apigateway). To request the server to execute a server-side script, the client write directly the request JSON object to the stream, in the following form:

{
    "path": [VFS path to the server side script],
     "parameters": [parameters of the server-side script]
}

or

{
    "code": [server side code snippet to be executed]
}

After receiving the request, the server starts to execute the script, during the execution, any response from the server should be immediately streamed back to the client.

Comments

The comment editor supports Markdown syntax. Your email is necessary to notify you of further updates on the discussion. It will be hidden from the public.
Powered by antd server, (c) 2019 - 2021 Xuan Sang LE