-
Notifications
You must be signed in to change notification settings - Fork 5
[WIP] API for app to app communication
Note: Relevant discussion in https://github.com/kontalk/androidclient/issues/744
This page describes the desired API. It is still an early work in progress and will change through time.
The request format will be reasonably RESTful. All communication is asynchronous. When the web client requests information, it may be returned at any time. The Android client is also allowed to send responses without the web client requesting it (if it wants to notify the web client of changes), the web client is expected to apply changes on receiving them.
The API will always return JSON, containing the command and result. If binary data has to be sent, it will be base-64 encoded.
The result may not contain all the desired fields. In case fields are missing, the web client is expected to only update the given fields in its own internal data.
Get a list of all contacts.
Example request:
GET contacts
Example response:
{
"command": "contacts",
"result": [{
"id": "[email protected]"
}, {
"id": "[email protected]"
}]
}
Get all info of a single user
Example request:
contact/[email protected]
Example response:
{
"command": "contact",
"result": {
"id": "[email protected]",
"name": "John Doe",
"status": "",
"picture": <base64-encoded image>,
"lastActivity": 0
}
}
Get the name of a contact.
Example request:
contact/[email protected]/name
Example response:
{
"command": "contact",
"result": {
"id": "[email protected]",
"name": "John Doe"
}
}
Get the status of a contact.
Example request:
contact/[email protected]/status
Example response:
{
"command": "contact",
"result": {
"id": "[email protected]",
"status": "The name is Doe. John, Doe."
}
}
Get the profile picture of a contact.
Example request:
contact/[email protected]/picture
Example response:
{
"command": "contact",
"result": {
"id": "[email protected]",
"picture": <base64-encoded image>
}
}
### contact/*id*/lastActivity
Get the amount of minutes since last activity of a contact.
If lastActivity is 0, the contact is currently active.
Example request:
contact/[email protected]/lastActivity
Example response:
{ "command": "contact", "result": { "id": "[email protected]", "lastActivity": 9 } }
## Conversation management
### conversations
Get a list of all conversations.
Example request:
GET conversations
Example response:
{ "command": "conversations", "result": [{ "id": "[email protected]", }, { "id": "kittenloversanonymous", }] }
### conversation/*id*
Get all info of a single conversation.
Example request:
conversation/kittenloversanonymous
Example response:
{ "command": "conversation", "result": { "id": "kittenloversanonymous", "name": "Kitten Lovers Anonymous", "type": "group", "participants": [{ "id": "[email protected]", "role": "member" }, { "id": "[email protected]", "role": "admin" }, "messages": [{ "from": "[email protected]", "content": "Welcome to my group!", "timestamp": 1464386320 }, { "from": "[email protected]", "content": "Thanks!", "timestamp": 1464386340 }] } }