Kahla API Document

Server address

There are three servers for Kahla.

Server Address Allow Cross-Domain Limit Cookies Code Branch Usage Corresponding Kahla Client
server.kahla.app https://web.kahla.app Yes master hosting production version of Kahla server master
staging.server.kahla.app https://staging.kahla.app Yes dev hosting staging version of the Kahla server dev
dev.server.kahla.app http://localhost:4200 No dev For developers locallly debugging Kahla.App Local

Protocol

All of Kahla's server communications use the mandatory HTTPS protocol and the HSTS standard.

Database

The database of the staging server and the local debugging server is the same one, and the database may be cleaned regularly, and the data persistence is not guaranteed.

The production Kahla server uses an independent database, and the database will never be cleaned up.

If you are a contributor to Kahla, please note that the debugging API is used in the debugging environment, the staging API is used in the pre-deployment environment, and the production API is used only in the production environment.

Authentication

Kahla server uses cookie-based authentication. In other words, all cookies must be carried when accessing all APIs that require login privileges.

When Kahla's client is running, it must work in the cross-domain address allowed by the target server, otherwise it will not be able to carry cookies.

For available domains, please reference the serer address.

File upload

This API connects to our new storage base: Probe. Probe is powerful. Supports multiple sites and folders.

The document of the API is here

Different conversations have different folders. And different users have different permissions to access. Which makes files safer to save, and API simpler.

Probe API returns file path with a pattern: sitename/path/filename.

For example, if you call the Init icon upload API, the server will return you an upload path like:

{
  "value":"https://probe.aiursoft.com/Files/UploadFile/kahla-user-icon/2019-11-11?pbtoken=eyJzaXRlTmFtZSI6ImthaGxhLXVzZXItaWNvbiIsInVuZGVyUGF0aCI6IjIwMTktMTEtMTEiLCJwZXJtaXNzaW9ucyI6IlVwbG9hZCIsImV4cGlyZXMiOiIyMDE5LTExLTExVDA0OjE1OjI2LjEyMDc3MVoifQ%3D%3D.G%2BEA4PWzfmLPWpKeSUbaufqzs7WyncHdXZPTj4Ca8jTcoIwX%2F6kskbBqXJNjJmhVW3j%2BtpMemxBaDl6pu0XnwvKXrJHip21yM8Jp6eTX4Vd9cSvLS2feD44VuybQ6liQlcWhXk%2F%2FWyUkESZilIQRFp2Gs9OJ0lObGBc5MLnDs8s%3D&recursivecreate=True",
  "code":0,
  "message":"Token is given. You can not upload your file to that address. And your will get your response as 'FilePath'."}

When you get the upload path, you can upload a file to it. The document of the upload API is here.

When you successfully uploaded a file, possible response is:

{
  "siteName": "kahla-user-icon",
  "filePath": "kahla-user-icon/2019-11-11/IMG_20190924_193959.jpg",
  "internetPath": "https://kahla-user-icon.aiursoft.io/2019-11-11/IMG_20190924_193959.jpg",
  "fileSize": 1718140,
  "code": 0,
  "message": "Successfully uploaded your file."
}

We use the filePath with sitename/path/filename pattern to represent a file instead of a file ID. You should use this pattern to save and send messages representing files instead of the file id.

filePath is not url encoded. And it can not be used as download address directly.

Never use the internetPath property to prevent hackers reference the files from their own server. Please reference the file download part

To maintain the users' icon, we used to call the Me API. Me API now returns iconFilePath which also respect the pattern.

File download

Now as we all know, you can easily get a file represented by sitename/path/filename. But you can not download it that way. To download, you need to add some protocol names.

Full download pattern

Just add:

https://probe.aiursoft.com/Download/Open/{The pattern with url encoded without encoded `/`}

For example, if you get a file with the pattern: mynewsite/myfolder/mysubfolder/img_20190727_143308.jpg.

  • The path of this file is /.
  • The site name of this file is mynewsite.
  • The path name of this file is myfolder/mysubfolder.
  • The file name of this file is img_20190727_143308.jpg

Add the head https://probe.aiursoft.com/Download/Open/

Get the download address:

https://probe.aiursoft.com/Download/Open/mynewsite/myfolder/mysubfolder/img_20190727_143308.jpg

If you add Download/File instead of Download/Open, the server will return the file as binary, which helps the browser to download.

https://probe.aiursoft.com/Download/File/mynewsite/myfolder/mysubfolder/img_20190727_143308.jpg

Simplified pattern

Just add:

https://{siteName}.aiursoft.io/{path}/{fileName}

For example, if you get a file with the pattern: mynewsite/myfolder/mysubfolder/img_20190727_143308.jpg.

  • The path of this file is /.
  • The site name of this file is mynewsite.
  • The path name of this file is myfolder/mysubfolder.
  • The file name of this file is img_20190727_143308.jpg

Get the download address:

https://mynewsite.aiursoft.io/myfolder/mysubfolder/img_20190727_143308.jpg

Messages

Kahla message patterns

Video:

[video]mynewsite/myconversation/img_20190727_143308.mp4

Audio

[audio]mynewsite/myconversation/img_20190727_143308.mp4

File:

[file]mynewsite/myconversation/img_20190727_143308.jpg|myfile.exe(file name)|1.24G(file size)

Image:

[img]mynewsite/myconversation/img_20190727_143308.jpg|80|80(For image size)

Shared group:

[group]708 (group id)

Shared user:

[user]6da0802e-18e4-4a76-99a5-47878dd7b8a5 (user id)

File compressing

The compression algorithm of Probe has been modified. It is now more recommended to use only one parameter to get the compressed image.

For example: specify only w or just h. Then the value of another dimension, Probe itself calculates, and maintains the aspect ratio of the original image.

These changes I am looking forward to can help simplify some of the fucking code in Kahla.App and save an extra parameter.

Kahla can not calculate the width and height of the real picture, but directly specify only one parameter to quickly complete the rendering of the picture.

Example:

https://probe.aiursoft.com/Download/InSites/usericon/53de617d093040bab113a6508dbcdd19.png?w=100

In addition: forcing two parameters to be specified will still cause the Probe to compress with the specified target parameters. However, in this case, the parameter passer must be responsible for maintaining the aspect ratio of the image.

Messages sent detection

This API may help detect if your message was sent:

  • Send message will notify the sender by WebSocket and web push.
  • Send message API will auto-clear unread.
  • Message ID (Guid type) and send time is determined by the client side. But it can't be far from API calling time.

So, after the send message response, the client can just give the temp message send time and don't have to clear it. And the client don't have to get messages to clear unread.


As for GetMessages API:

The skipFrom argument now is for:

For which message you want to skip from. Input that message's GUID.

If the target message not found or argument not passed, it will not skip any message.

That message you specified will not be included in the result.


As for SendMessage API and GetMessages API

Now, sending message request a unique GUID. This will be saved as the message's unique Id.

It must be a valid GUID, for example: 8fe1dd34-7430-4650-8b0a-8587d39dd412.

Consider code:

function uuidv4() {
  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function(c) {
    var r = Math.random() * 16 | 0, v = c == 'x' ? r : (r & 0x3 | 0x8);
    return v.toString(16);
  });
}

console.log(uuidv4());

And the ID will be returned when returning a message from Json.