Skip to content

API.md

Latest commit

 

History

History
243 lines (166 loc) · 6.95 KB

API.md

File metadata and controls

243 lines (166 loc) · 6.95 KB

Anonomi Postbox Rest API

All postbox requests are authenticated with a Bearer Authorization HTTP header:

Authorization: Bearer 0000000000000000000000000000000000000000000000000000000000000000

To make a request to a postbox via Tor (running with a SOCKS proxy on the system already), the following command can be used.

curl --socks5-hostname 127.0.0.1:9050 -v -H "Authorization: Bearer 0000000000000000000000000000000000000000000000000000000000000000" http://example.org

Postbox Management (owner only)

Setup/Pairing (owner only)

Used by owner to pair with or setup their postbox (which needs to be in the setup state). Request is authenticated by a single-use token from the QR code shown by the postbox app. The request contains no other data.

PUT /setup

If the token has not been used, the call returns a HTTP status code 201 Created. The JSON response body will contain the long-term owner auth token for subsequent calls, and a list of API versions that the Postbox supports. Response example:

{
  "token": "2b063589ac6203feffa40c120716b79a472d607c089c42203819f363dee3266c",
  "serverSupports": [
    { "major": 1, "minor": 0 },
    { "major": 1, "minor": 1 }
  ]
}

If the token has already been used then the call returns 401 Unauthorized and Anonomi should tell the user to reset/wipe the postbox and try again.

After a successful response, Anonomi performs the requests it does on each new connection to the postbox, e.g. syncing contacts. If Anonomi crashes after the postbox processes the pairing call, but before Anonomi receives the reply, then after restarting Anonomi the user should be led through the steps to wipe the postbox and start again, whenever the user visits the postbox status screen. If we lose the connection, but Anonomi doesn't crash after the postbox processes the pairing call, but before Anonomi receives the reply, then the Anonomi UI leads the user through the steps to reset/wipe the postbox and start again as well.

Get list of supported API versions (owner only)

Retrieves the list of API versions that the Postbox supports.

GET /versions

Returns 200 OK with a list of supported versions. Response example:

{
  "serverSupports": [
    { "major": 1, "minor": 0 },
    { "major": 1, "minor": 1 }
  ]
}

Remote wipe (owner only)

Unpairs Anonomi and the postbox. Resets postbox state to that after first install ( e.g. removes all stored files as well).

DELETE /

Returns an empty 204 No Content response if successful or an error code if not.

Status request (owner and contacts)

Checks whether postbox is running.

GET /status

Always returns 200 OK.

Contact Management (owner only)

Add a contact (owner only)

Adds a new contact to the postbox.

POST /contacts

Anonomi generates random 32-byte token, inboxId and outboxId encoded as hexadecimal strings and sends them along with its contactId.

Example request body:

{
  "contactId": 3,
  "token": "3dd6c6b313f692bd10e33099ed0819a5f721478213d8f632af5b3fe203e2e222",
  "inboxId": "07e6eacc0eca14547481498ec6a46cf90ddc4b8d7d87e5a97d03377695fae394",
  "outboxId": "2a067589ac6203feffa40c120716b79a472d607c089c42203819f363dee3266c"
}

The API responds with HTTP status code 201 Created for a successful POST. If the contactId is already in use, 409 Conflict is returned.

Delete a contact (owner only)

DELETE /contacts/$contactId

$contactId is the integer contact ID the contact was added with. Returns 200 OK when deletion was successful.

Get list of contacts (owner only)

Gets list of contacts managed by the postbox identified by their contactId.

GET /contacts

Returns 200 OK with a list of contact IDs like this:

{
  "contacts": [ 1, 3, 4, 6 ]
}

File Management (owner and contacts)

A file contains a stream of message, events etc.

Adding a file to a folder (owner and contacts)

Used by contacts to send files to the owner and by the owner to send files to contacts. The owner can add files to the contacts' inboxes and the contacts can add files to their own outbox.

POST /files/$folderId

The postbox checks if the provided auth token is allowed to upload to $folderId which is either an inboxId or an outboxId of a contact.

If the folder does not exist or the auth token is not allowed to upload to it, 404 Not Found is returned.

The file content is a raw byte stream in the request body. The postbox chooses a random string for the file ID (32 hex encoded bytes). Returns 200 OK if upload was successful (no 201 as the uploader does not need to know the $fileName).

List files available in a folder (owner and contacts)

Used by owner and contacts to list their files to retrieve.

GET /files/$folderId

The postbox checks if provided auth token is allowed to download from $folderId which is either an inboxId or an outboxId of a contact.

If the folder does not exist or the auth token is not allowed to download from it, 404 Not Found is returned.

Returns 200 OK with the list of files in JSON (example):

{
  "files": [
    { "name": "ae6751c8e90fa347e24afaa977e180cdd7cfd8fa5194954f6467d2cc51c87640", "time": 1629816408 },
    { "name": "5aff93e611bc338dffa0c2337b416656e583e6eba23602a209633eb2362e2aa3", "time": 1629816410 },
    { "name": "d76dba27aaf763de8a2e8c543b3bb5969fa32fb398816e301c577e619d4d3232", "time": 1629816418 }
  ]
}

The files are listed in ascending order of timestamp.

Download a file (owner and contacts)

Used by owner and contacts to retrieve a file.

GET /files/$folderId/$fileName

Checks if the provided auth token is allowed to download from $folderId which is either an inboxId or an outboxId of a contact.

If the folder does not exist or the auth token is not allowed to download from it, 404 Not Found is returned.

Returns 200 OK if successful with the files' raw bytes in the response body.

Delete a file (owner and contacts)

Used by owner and contacts to delete files.

DELETE /files/$folderId/$fileName

Checks if provided auth token is allowed to download from $folderId which is either an inboxId or an outboxId of a contact.

If the folder does not exist or the auth token is not allowed to download from it, 404 Not Found is returned.

Returns 200 OK if deletion was successful.

List folders with files available for download (owner only)

Lists all contact outboxes that have files available for the owner to download.

GET /folders

Checks if provided auth token is belonging to the owner.

Returns 200 OK with the list of folders that have files available to download, in JSON (example):

{
  "folders": [
    { "id": "ae6751c8e90fa347e24afaa977e180cdd7cfd8fa5194954f6467d2cc51c87640" },
    { "id": "3dd6c6b313f692bd10e33099ed0819a5f721478213d8f632af5b3fe203e2e222" },
    { "id": "5aff93e611bc338dffa0c2337b416656e583e6eba23602a209633eb2362e2aa3" }
  ]
}