API Guide ¶
Overview ¶
The Comet Server can be controlled via an API over HTTP / HTTPS. Every action that can be performed via the Comet Server web interface or the Comet Backup client software interface can also be performed by the API.
You can see the full list of API endpoints in the "API Reference" document. This document includes information about
- Supported API endpoints,
- Data structures used by the API, and
- Constant values used by the API.
This document ¶
This document is available from two locations:
- Online at cometbackup.com, where the API documentation refers to the latest released version of Comet Server
- In your Comet Server install directory in the
docs/
subdirectory, where the API documentation refers to your installed version of Comet Server
Comet's API is backward compatible, so we recommend using the latest available documentation. However, you can use the local copy to access documentation for your specific version of Comet Server if necessary.
Quick Start (examples) ¶
These examples make a network request to a Comet Server at http://127.0.0.1/
, with the Auth Role enabled, using the administrator credentials admin:admin
, to retrieve a list of user accounts.
cURL ¶
curl -X POST -d 'Username=admin&AuthType=Password&Password=admin' 'http://127.0.0.1/api/v1/admin/list-users'
PHP ¶
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'http://127.0.0.1/api/v1/admin/list-users');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query([
'Username' => 'admin',
'AuthType' => 'Password',
'Password' => 'admin',
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
var_export($response);
Powershell ¶
Invoke-Webrequest -Uri http://127.0.0.1/api/v1/admin/list-users -Method POST -Body @{Username="admin"; AuthType="Password"; Password="admin"} | select Content
VBScript ¶
set oRequest = CreateObject("Microsoft.XMLHTTP")
oRequest.open "POST", "http://127.0.0.1/api/v1/admin/list-users", false
oRequest.setRequestHeader "Content-Type", "application/x-www-form-urlencoded"
oRequest.send "Username=admin&AuthType=Password&Password=admin"
MsgBox oRequest.responseText
Go (golang) ¶
import (
"fmt"
"net/http"
"io/ioutil"
)
func ListUsers() {
resp, err := http.Post(
"http://127.0.0.1/api/v1/admin/list-users",
"application/x-www-form-urlencoded",
[]byte("Username=admin&AuthType=Password&Password=admin"),
)
if err != nil {
panic(err)
}
defer resp.Body.Close()
body, err := ioutil.ReadAll(resp.Body)
if err != nil {
panic(err)
}
fmt.Println(string(body))
}
Special APIs ¶
Single sign-on ¶
You can use Comet's API to integrate single sign-on into Comet Server.
-
Use the
AdminAccountSessionStart
API to generate a session key for the administrative user. -
Open the Comet Server web interface in a new window.
- Submit an HTML
postMessage
event to the Comet Server window, containing an object in the format{msg:"session_login",username:"",sessionkey:""}
providing a valid username and session key.
This approach means it is not necessary to expose the administrator credential to the end user.
Live event streaming ¶
You can use Comet's API to receive live notifications of new events on the Comet server. This includes notifications of new jobs, completed jobs, and user profile configuration changes.
-
Make a GET request to
/api/v1/events/stream
. -
The server will perform an HTTP Upgrade to a WebSocket connection.
-
The client must emit five text message frames in order, containing
Username
,AuthType
,Password
,SessionKey
, andTOTP
parameter values respectively. -
If the authentication failed, the server will emit a text message frame containing the string
403 Unauth
, and then drop the connection. If the authentication succeeded, the server will emit a text message frame containing the string200 OK
. - Communication then proceeds in an API-specific manner.