-
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 or never. The web client should not expect an answer to each request.
While this documentation talks about example requests and responses, the responses may also be sent either from the Android client when something changes (to send an update to the web client), or from the web client to the Android client to change something. The web client should assume that the info has not been changed until it receives the same response back from the Android client.
The content, either due to a specific request or when received due to a partial change, 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 and leave the other fields unmodified. A field should only be removed if the response explicitly contains null for this field.
The API will always return JSON, containing the command and content. If binary data has to be sent, it will be base-64 encoded.
API functions that cannot be explicitly requested will lack an example request in the documentation.
Get the API version used.
Example request:
version
Example response:
{
"command": "version",
"content": {
"api": 1
}
}
Get all information about the user.
Example request:
me
Example response:
{
"command": "me",
"result": {
"id": "[email protected]",
"name": "Mario",
"status": "It's a me, Mario!",
"picture": <base64-encode picture>
}
}
Get the name of the user.
Example request:
me/name
Example response:
{
"command": "me",
"content": {
"id": "[email protected]",
"name": "Mario"
}
}
Get the status message of the user.
Example request:
me/status
Example response:
{
"command": "me",
"content": {
"id": "[email protected]",
"status": "It's a me, Mario!"
}
}
Get the picture of the user.
Example request:
me/picture
Example response:
{
"command": "me",
"result": {
"id": "[email protected]",
"picture": <base64-encode picture>
}
}
Get a list of all contacts.
Example request:
contacts
Example response:
{
"command": "contacts",
"content": [{
"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",
"content": {
"id": "[email protected]",
"name": "John Doe"
}
}
Get the status of a contact.
Example request:
contact/[email protected]/status
Example response:
{
"command": "contact",
"content": {
"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",
"content": {
"id": "[email protected]",
"picture": <base64-encoded image>
}
}
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",
"content": {
"id": "[email protected]",
"lastActivity": 9
}
}
Remove a contact.
Example response:
{
"command": "contact",
"action": "remove",
"result": {
"id": "[email protected]"
}
}
Get a list of all conversations.
Example request:
conversations
Example response:
{
"command": "conversations",
"content": [{
"id": "[email protected]"
}, {
"id": "kittenloversanonymous"
}]
}
Get all info of a single conversation.
The list of messages is limited to the last 25(?) messages. This should allow the user to have a basic idea of what the conversation was about, without allowing a malicious web client to extract the whole conversation history.
Example request:
conversation/kittenloversanonymous
Example response:
{
"command": "conversation",
"content": {
"id": "kittenloversanonymous",
"name": "Kitten Lovers Anonymous",
"type": "group",
"picture": <base64-encoded image>,
"participants": [{
"id": "[email protected]",
"role": "member"
}, {
"id": "[email protected]",
"role": "admin"
}],
"messages": [{
"from": "[email protected]",
"type": "text/plain",
"sent": 1464386320,
"received": 1464386320,
"content": "Welcome to my group!"
}, {
"from": "[email protected]",
"type": "image/jpeg",
"sent": 14643863222,
"received": 1464386323,
"content": <base64-encoded image>
}, {
"from": "[email protected]",
"type": "text/plain",
"sent": 1464386340,
"content": "Thanks!"
}]
}
}
Get the name of a single conversation. In one-on-one conversations, this is the same as the name of the contact.
Example request:
conversation/kittenloversanonymous/name
Example response:
{
"command": "conversation",
"content": {
"id": "kittenloversanonymous",
"name": "Kitten Lovers Anonymous"
}
}
Get the type of a single conversation.
Returns "group" for group conversations and "single" for one-on-one conversations.
Example request:
conversation/kittenloversanonymous/type
Example response:
{
"command": "conversation",
"content": {
"id": "kittenloversanonymous",
"name": "group"
}
}
Get the picture of a single conversation. In one-on-one conversations, this is the same as the contact picture.
Example request:
conversation/kittenloversanonymous/picture
Example response:
{
"command": "conversation",
"content": {
"id": "kittenloversanonymous",
"picture": <base64-encoded image>
}
}
Get the list of participants of a single conversation.
If this is not a group chat, no response will be given.
Example request:
conversation/kittenloversanonymous/participants
Example response:
{
"command": "conversation",
"content": {
"id": "kittenloversanonymous",
"participants": [{
"id": "[email protected]",
"role": "member"
}, {
"id": "[email protected]",
"role": "admin"
}
}
}
Get the list of messages of a single conversation.
The list of messages is limited to the last 25(?) messages. This should allow the user to have a basic idea of what the conversation was about, without allowing a malicious web client to extract the whole conversation history.
Example request:
conversation/kittenloversanonymous/messages
Example response:
{
"command": "conversation",
"content": {
"id": "kittenloversanonymous",
"messages": [{
"from": "[email protected]",
"type": "text/plain",
"sent": 1464386320,
"received": 1464386320,
"content": "Welcome to my group!"
}, {
"from": "[email protected]",
"type": "image/jpeg",
"sent": 14643863222,
"received": 1464386323,
"content": <base64-encoded image>
}, {
"from": "[email protected]",
"type": "text/plain",
"sent": 1464386340,
"content": "Thanks!"
}]
}
}
Remove a conversation. In a single conversation, this is equivalent to pressing "Delete chat" on the Android client. In a group conversation, this leaves and deletes the chat.
Example response:
{
"command": "conversation",
"action": "remove",
"content": {
"id": "kittenloversanonymous"
}
}
Send or receive a chat message.
The id is an unique id for each message. If a message with this ID already exists, the received fields need to be updated.
When the web client sends a message to the Android client, it should not send an id or pending/sent/received timestamp.
Example response:
{
"command": "message",
"content": {
"id": 7,
"conversation": "kittenloversanonymous",
"from": "[email protected]",
"type": "text/plain",
"pending": 1464439720,
"content": "That's a cute picture"
}
}
Example response upon successful sent:
{
"command": "message",
"content": {
"id": 7,
"pending": null,
"sent": 1464439721
}
}
Remove a message.
Example response:
{
"command": "message",
"action": "remove",
"content": {
"id": 7
}
}