Server API - AttiliaTheHun/Songbook-Manager GitHub Wiki
Following is the complete list of API routes the web server as given provides for interaction. They are all accessible at http(s)://your-server-address.your-domain/api/x
where x
naturally means the target endpoint.
/version-timestamp/ [GET]
Returns the version_timestamp
in the form of number (long). Source code
/index/ [GET]
Returns the songbook index.
Required permission: READ
. Source code
/data/
This endpoint allows for songbook data download and upload.
Uploading data
For uploading, a POST
request with authentication token must be sent. Furthermore the request body must contain a .zip
file with the corresponding data and the request index. Possible response codes are
201
on success400
if the request has no body or if the request cannot be processed401
if a token withoutWRITE
permission was used503
if there is a serious configuration issue on the server
Downloading data
For downloading, a GET
request with authentication token must be sent. The server should respond with a load_request.zip
file. If the request has no body, this file will contain the entire remote songbook. It is possible to specify the files to be downloaded by sending a load index in the request body. Possible response codes are
200
on success400
if the request index can not be parsed or the HTTP headers are incorrect401
if a token withoutREAD
permission was used503
if there is a serious configuration issue on the server
The server will return 405
Method not allowed if another HTTP method is used.
Source code, upload.php, download.php
/resources/ [GET]
Returns a resources.zip
file. Source code
// TODO:
/backups [POST]
Creates a complete backup of the songbook. Returns HTTP 201 code with "Backup created under '$filename'" message upon success.
Required permission: BACKUP
. Source code
/backup/restore/ [GET]
// TODO
Required permission: RESTORE
. Source code
/backup/backups/ [GET]
Lists all available backups and their date of creation. The output may look like this
{ "complete": ["complete_backup_0.zip December 29 2002 22:16:23"],
"inverse": [
"inverse_backup_0.zip May 02 2005 12:03:32"
"inverse_backup_1.zip May 09 2005 15:15:13"
]
}
/admin/freeze-token/ [POST]
Freezes specified authentication tokens. Such tokens can no longer be used for authentication and lose all their previous permissions. The endpoint expects a request simillar to this:
{ "freeze": [0, 7, 8] }
The numbers signify indices of the tokens in the tokens.json
file on the server. The /admin/tokens/
endpoint returns tokens in the order corresponding to this indexing. On success HTTP 201 is returned.
Required permission: MANAGE_TOKENS
. Source code
/admin/create-token/ [POST]
// TODO
Required permission: MANAGE_TOKENS
. Source code
/admin/tokens/ [GET]
Lists the available authentication tokens. The output is ordered the same way the tokens are stored at the server and preserves token indices. An example response may look like this:
["Jimbo's token 2008/12/23 11100",
"Karen's token frozen 2006/4/15 10000",
"Admin token 2008/12/20 11111"]
First comes the token name and if the token is frozen, "frozen"
is noted. Then comes the token creation date and finally the token permissions as a bitmap. Permissions are ordered from least important (READ
) to most important (MANAGE_TOKENS
) where 1
means the permission is granted and 0
means it does not exist for this token.
Required permission: MANAGE_TOKENS
. Source code