Support

Documentation

Client and server data formats

For historical reasons, version 1 requires that you encapsulate the data you send to the server and specifies that the returned data will also be returned encapsulated. The encapsulation in this context means that the actual data is passed as a string inside another, outer, JSON message.

For example, if you want to pass the message:

{
  foo: "bar"
}

You would need to encapsulate it like this:

{
  encapsulation: 1,
  body: {
    challenge: "foo:3858f62230ac3c915f300c664312c63f",
    method: "example",
    data: "{foo:\"bar\"}"
  }
}

In the past this allowed the data string (body.data) to be encrypted using AES. This was a misguided attempt to use encryption for authentication (which is a bad idea due to attacks against the encryption algorithm) and also as a way to work around the fact that the majority of sites back in early 2011 didn't use HTTPS.

Fast forward to 2019, when we started working on Akeeba Backup 7. It was pretty clear that using encryption for authentication was a liability, not an asset. Moreover, most sites would now use HTTPS since the cost of SSL/TLS certificates had dropped to zero thanks to the free of charge certification authority Let's Encrypt.

Therefore the decision was made to drop all encapsulations except for RAW from Akeeba Backup 7. This documentation has been updated to reflect this change.

Further changes in the horizon

Within 2020 we are going to introduce the second version of our API. The following changes will take place.

There will be no encapsulation of the message. The only reason for encapsulation was the support of different encryption methods. This is no longer necessary, therefore encapsulation can be dropped completely.

Authentication will move to tokens. In the current API implementation authentication takes place using an MD5 hash of a random salt and a static shared key. We had to do that to avoid having the actual key appear in server logs since it's part of the GET query. In the new API version we will be using a token that's sent to your site as an HTTP header. You will be able to regenerate or revoke your token anytime. This simplifies token management and does away with the need to enforce a minimum password complexity for the secret key as we were doing in the past.

Some API methods will be dropped. Some API methods have been marked deprecated and will be removed from the next API version.

Co-existence of the two API versions. For a brief period of time both API versions will co-exist. This will give a few months for third party implementations to catch up with the new API.

Client-side

The client is sending its requests to the server over a standard HTTP GET operation to the endpoint URI of the component. An end-point URI looks like http://www.example.com/index.php?option=com_akeeba&view=json&format=raw&json=<data>. It goes without saying, www.example.com is to be replaced by the FQDN of the site where Akeeba Backup is installed. The <data> part of the URI is the JSON-encoded Request Object.

[Note]Note

API endpoints for Akeeba Backup for WordPress and Akeeba Solo are different than the one illustrated above. Please consult the Schedule Automatic Backups page of each software to learn about the API endpoints.

Exceptions to the GET rule: Some request methods may require you to use POST instead of GET. Such exceptions will be documented in the respective method.

Alternative endpoint URL: Since API level 319 you can substitute format=raw with format=component. This increases the compatibility with poorly written third party Joomla! system plugins and we strongly recommend always using that.

The Request Object

The Request Object is a JSON object with the following fields:

encapsulation

An Encapsulation Identifier constant (integer), defining the encapsulation method of the body

body

A JSON string representing the Request Body, encoded in the specified encapsulation

The Request Body

The Request Body is a JSON object with the following fields:

challenge

This field consists of a salt string and an MD5 hash, separated by a colon, like this: salt:md5. The salt can be an arbitrary length alphanumeric string. The md5 part of the challenge is the result of the MD5 hash of the concatenated string of the salt and the Akeeba Backup front-end secret key, as configured in the component's Options. For example, if the salt is foo and the secret key is bar, the md5 is md5(foobar) = 3858f62230ac3c915f300c664312c63f, therefore the challenge is foo:3858f62230ac3c915f300c664312c63f.

method

The name of the method you want the server to execute

data

A JSON object containing the parameters to be passed to the method.