Skip to content

[WIP] API for app to app communication

TheLastProject edited this page May 28, 2016 · 12 revisions

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.

General notes

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.

Functions

User management

me

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>
    }
}

me/name

Get the name of the user.

Example request:

me/name

Example response:

{
    "command": "me",
    "content": {
        "id": "[email protected]",
        "name": "Mario"
    }
}

me/status

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!"
    }
}

me/picture

Get the picture of the user.

Example request:

me/picture

Example response:

{
    "command": "me",
    "result": {
        "id": "[email protected]",
        "picture": <base64-encode picture>
    }
}

Contact management

contacts

Get a list of all contacts.

Example request:

contacts

Example response:

{
    "command": "contacts",
    "content": [{
        "id": "[email protected]"
    }, {
        "id": "[email protected]"
    }]
}

contact/id

Get all info of a single user

Example request:

Example response:

{
    "command": "contact",
    "result": {
        "id": "[email protected]",
        "name": "John Doe",
        "status": "",
        "picture": <base64-encoded image>,
        "lastActivity": 0
    }
}

contact/id/name

Get the name of a contact.

Example request:

contact/[email protected]/name

Example response:

{
    "command": "contact",
    "content": {
        "id": "[email protected]",
        "name": "John Doe"
    }
}

contact/id/status

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."
    }
}

contact/id/picture

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>
    }
}

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",
    "content": {
        "id": "[email protected]",
        "lastActivity": 9
    }
}

Contact removal

Remove a contact.

Example response:

{
    "command": "contact",
    "action": "remove",
    "result": {
        "id": "[email protected]"
    }
}

Conversation management

conversations

Get a list of all conversations.

Example request:

conversations

Example response:

{
    "command": "conversations",
    "content": [{
        "id": "[email protected]"
    }, {
        "id": "kittenloversanonymous"
    }]
}

conversation/id

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!"
        }]
    }
}

conversation/id/name

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"
    }
}

conversation/id/type

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"
    }
}

conversation/id/picture

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>
    }
}

conversation/id/participants

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"
        }
    }
}

conversation/id/messages

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!"
        }]
    }
}

Conversation removal

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"
    }
}

Message management

message

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
    }
}

Message removal

Remove a message.

Example response:

{
    "command": "message",
    "action": "remove",
    "content": {
        "id": 7
    }
}
Clone this wiki locally