System API allows to perform some system wide operations
All URI to the system API should start with /system
GET /system HTTP/1.1
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"
}
}
}
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:
os://packages/
(VFS path, refer to the VFS section to know about the format)home://.packages
, but this VFS path can be configured by each user.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.
POST /system/packages HTTP/1.1
Content-Type: application/json
{
"command": "list",
"args": {
"paths": [
"os://packages",
"home://.packages"
]
}
}
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
}
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.
POST /system/packages HTTP/1.1
Content-Type: application/json
{
"command": "cache",
"args": {
"paths": [
"os://packages",
"home://.packages"
]
}
}
On success the response should be:
{"result":true,"error":false}
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.
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
On success the response should be:
{"result":true,"error":false}
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:
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
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]
}
On success, the operation returns the response of the execution in any format
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.