META

Ramses Server API

The Ramses Server is used to backup and sync data across Ramses Applications and workstations.

It provides a standard http(s) REST API. If you’re developping your own client (or contributing to Ramses Client), you can easily exchange data with the server using this reference.

Queries must be a POST request; the body must be JSON encoded, the Content-Type being application/json.

Only one attribute must be set directly in the URL (like a GET request), the name of the query itself.

For now, the server only supports the UTF-8 charset, so it is not mandatory to add the charset in the Content-Type, and any value other than utf-8 will be ignored. This may change in future versions.

Queries

The server provides a single endpoint, which is the root of the folder where it’s installed. For example, for a server installed in a folder called example on the server at https://ramses.rxlab.io, the endpoint will be https://ramses.rxlab.io/example.

To query the server, you only need to add the query name as a parameter to this URL. For example, the URL for the ping query is https://ramses.rxlab.io/example/?ping.

All queries must be accompanied with a JSON object in the post body, containing at least these values:

{
    "version": "0.6.0"
}

Replies

The server replies to all queries with a JSON object, containing these values:

{
    "accepted": true,
    "success": true,
    "message": "Server ready.",
    "query": "ping",
    "content": {},
    "serverUuid": "unique-uid",
    "debug": []
}

Debug and logs

The debug value of the reply is an array containing these objects:

{
    "date": "2022-11-25 13:05:24",
    "level": "DEBUG",
    "message": "A debug log entry"
}

Syncing data

This is the process to sync data with the server.

  1. ping to check if the server is available and check its version. This is mandatory to initiate the session before being able to log in.
  2. login to authenticate yourself.
  3. sync your data.

For the examples in this documentation, we assume the ramses server is available at https://ramses.rxlab.io/example/.

Note

For the sake of readability, the JSON replies are pretty formatted with indentation and new lines in this documentation, but the server actually uses one-line replies.

ping

Query: https://ramses.rxlab.io/example/?ping

Request body

{
    "version": "0.6.0"
}

Reply

The server replies with:

{
    "accepted": true,
    "success": true,
    "message": "Server ready.",
    "query": "ping",
    "content": {
        "installed": true,
        "version": "0.6.0"
    },
    "serverUuid": "unique-uid",
    "debug": []
}

login

Query: https://ramses.rxlab.io/example/?login

Request body

{
    "version": "0.6.0",
    "username": "Duduf",
    "password": "123456"
}

Reply

The server replies with:

{
    "accepted": true,
    "success": true,
    "message": "Successful login. Welcome Duduf!",
    "query": "login",
    "content": {
        "username": "Duduf",
        "uuid": "uuid",
        "token": "token"
    },
    "serverUuid": "unique-uid",
    "debug": []
}

sync

Query: https://ramses.rxlab.io/example/?sync

Request body

{
    "version": "0.6.0",
    "token": "token",
    "previousSyncDate": "2022-06-15 15:44:23",
    "tables":[
        {
            "name": "RamApplication",
            "modifiedRows": [
                {
                    "uuid": "123456",
                    "data": "{some data}",
                    "modified": "2022-07-15 15:44:23",
                    "removed": 0
                },
                {
                    "uuid": "789123",
                    "data": "{some other data}",
                    "modified": "2022-08-24 15:44:23",
                    "removed": 1
                }
            ]
        },
        {
            "name": "RamStep",
            "modifiedRows": [
                {
                    "uuid": "123456",
                    "data": "{some data}",
                    "modified": "2022-07-15 15:44:23",
                    "removed": 0
                },
                {
                    "uuid": "789123",
                    "data": "{some other data}",
                    "modified": "2022-08-24 15:44:23",
                    "removed": 1
                }
            ]
        },
        {
            "name": "RamUser",
            "modifiedRows": [
                {
                    "uuid": "123456",
                    "userName": "Duf",
                    "data": "{some data}",
                    "modified": "2022-07-15 15:44:23",
                    "removed": 0
                },
                {
                    "uuid": "789123",
                    "userName": "Ana",
                    "data": "{some other data}",
                    "modified": "2022-08-24 15:44:23",
                    "removed": 1
                }
            ]
        }
    ]
}

Reply

The server replies with:

{
    "accepted": true,
    "success": true,
    "message": "Data sync, OK!",
    "query": "sync",
    "content": {
        "tables":[
            {
                "name": "RamApplication",
                "modifiedRows": [
                    {
                        "uuid": "123456",
                        "data": "{some data}",
                        "modified": "2022-08-15 15:44:23",
                        "removed": 0
                    },
                    {
                        "uuid": "789123",
                        "data": "{some other data}",
                        "modified": "2022-08-26 15:44:23",
                        "removed": 1
                    }
                ]
            },
            {
                "name": "RamStep",
                "modifiedRows": [
                    {
                        "uuid": "123456",
                        "data": "{some data}",
                        "modified": "2022-08-15 15:44:23",
                        "removed": 0
                    },
                    {
                        "uuid": "789123",
                        "data": "{some other data}",
                        "modified": "2022-08-26 15:44:23",
                        "removed": 1
                    }
                ]
            }
        ]
    },
    "serverUuid": "unique-uid",
    "debug": []
}

clean

Query: https://ramses.rxlab.io/example/?clean

Deletes rows from tables, using the objects’ uuids.

Request body

{
    "version": "0.6.0",
    "token": "token",
    "tables": [
        {
            "name": "tableName",
            "rows": ["uuid1", "uuid2", "uuid3"]
        },
        {
            "name": "otherTable",
            "rows": ["uuid4", "uuid5", "uuid6"]
        }
    ]
}

Reply

The server replies with:

{
    "accepted": true,
    "success": true,
    "message": "Cleaned data, removed 6 rows.",
    "query": "clean",
    "content": {
        "count": 6
    },
    "serverUuid": "unique-uid",
    "debug": []
}

setPassword

Query: https://ramses.rxlab.io/example/?setPassword

Request body

{
    "version": "0.6.0",
    "token": "token",
    "newPassword": "new password",
    "currentPassword": "current password",
    "uuid": "user-unique-uid"
}

The server will check if the connected user is an administrator, and accept the request accordingly:

That means if there’s only one administrator, who has forgotten its current password, only the server provider - someone who has an actual access to the server files (via FTP for example) - can set a new password, using Ramses Server development tools.