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 success
• 400 if the request has no body or if the request cannot be processed
• 401 if a token without WRITE permission was used
• 503 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 success
• 400 if the request index can not be parsed or the HTTP headers are incorrect
• 401 if a token without READ permission was used
• 503 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"        
  ]
}

Source code

/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