This document defines a RESTful API for managing Shadowsocks servers.
The API server SHOULD use TLS client certificates to authenticate API users, or host the endpoints behind a secret path.
API errors MUST return a JSON object with at least an error message in the error field:
{
"error": "server not found"
}Get information about the server.
GET /
{
"server": "shadowsocks-go 1.13.0",
"apiVersion": "v1"
}A Shadowsocks server with EIH support can serve multiple users on a single port.
When a server has EIH configured, this API endpoint can be used to manage users. If EIH is not used, respond with 404 and a friendly error message.
GET /users
{
"users": [
{
"username": "database64128",
"uPSK": "oE/s2z9Q8EWORAB8B3UCxw=="
}
]
}POST /users
{
"username": "database64128",
"uPSK": "oE/s2z9Q8EWORAB8B3UCxw=="
}Successfully added the new user.
- A user with the same username already exists.
- Malformed request.
GET /users/:username
{
"username": "database64128",
"uPSK": "oE/s2z9Q8EWORAB8B3UCxw==",
"downlinkPackets": 64,
"downlinkBytes": 4096,
"uplinkPackets": 32,
"uplinkBytes": 2048,
"tcpSessions": 16,
"udpSessions": 8
}User not found.
PATCH /users/:username
{
"uPSK": "DL7Vrnv7sOdPPDghtxyxgg=="
}Successfully updated the user's uPSK.
- The provided uPSK is the same as the existing one.
- Malformed request.
User not found.
DELETE /users/:username
Successfully deleted the user.
User not found.
Get data usage stats.
GET /stats
?clear=true: also clear stats
{
"downlinkPackets": 64,
"downlinkBytes": 4096,
"uplinkPackets": 32,
"uplinkBytes": 2048,
"tcpSessions": 16,
"udpSessions": 8,
"users": [
{
"username": "database64128",
"downlinkPackets": 64,
"downlinkBytes": 4096,
"uplinkPackets": 32,
"uplinkBytes": 2048,
"tcpSessions": 16,
"udpSessions": 8
}
]
}