New feature: HTTP API
Hi all!
We are bringing out HTTP API for doveadm-server in master HEAD. This feature is experimental, and can be expected to have bugs in it and might not always work. If you feel like trying it out though, you can enable it in your configuration file:
doveadm_api_key = some-string
service doveadm { inet_listener http { port = 8080 } }
To use the API, you can go to http://host:8080/doveadm. GET request will print out possible commands, along with their parameters. If you have set API KEY, you need to include it in the request as X-API-Key header.
This API has been designed to resemble JMAP API since we are planning to implement it in future version.
The rule of thumb is that all the commands work as they would on cli, so the parameters are more or less the same. There are few exceptions, like 'field' parameter in some mail/mailbox commands.
Commands are executed by POSTin JSON to /doveadm. The JSON format is
[ ["command",{"parameter":"value"},"opaque identifier"], ["command",{"parameter":"value"},"opaque identifier"], ["command",{"parameter":"value"},"opaque identifier"], ... ]
Be warned though that even if it supports multiple commands, some commands still use i_fatal to terminate the server if they are unhappy. This will mean you will lose the whole result set, and get no output, so at this point it is safest option to run only one command at a time.
If you run into problems or discover issues, please report them in the usual manner to us.
Kind regards, Aki Tuomi Dovecot Oy
On 2016-02-20 17:09, aki.tuomi@dovecot.fi wrote:
To use the API, you can go to http://host:8080/doveadm.
The documentation says http://host:8080/doveadm/v1 which is it?
GET request will print out possible commands, along with their parameters. If you have set API KEY, you need to include it in the request as X-API-Key header.
The documentation says X-Doveadm-API, which is it?
A simple 1-line curl-example in the docs would do wonders :)
http://wiki2.dovecot.org/Design/DoveadmProtocol/HTTP
Thanks.
// Tom
On April 4, 2016 at 5:18 PM Tom Sommer mail@tomsommer.dk wrote:
On 2016-02-20 17:09, aki.tuomi@dovecot.fi wrote:
To use the API, you can go to http://host:8080/doveadm.
The documentation says http://host:8080/doveadm/v1 which is it?
GET request will print out possible commands, along with their parameters. If you have set API KEY, you need to include it in the request as X-API-Key header.
The documentation says X-Doveadm-API, which is it?
A simple 1-line curl-example in the docs would do wonders :)
http://wiki2.dovecot.org/Design/DoveadmProtocol/HTTP
Thanks.
// Tom
Hi!
Yes, you're right.
I'll add this line to the docs as well, and also I discovered a bug in the code. It will be fixed in next release. The response indicates X-Dovecot-API, but the code uses X-Doveadm-API, this has been fixed to X-Dovecot-API.
For now, if you want to use BASIC authentication, you set doveadm_password to something and use
curl -H "Authorization: Basic <base64 username:password>" http://server:8080/
to get acceptable routes
curl -H "Authorization: Basic <base64 username:password>" http://server:8080/doveadm/v1
to get acceptable commands and their parameters
curl -H "Authorization: Basic <base64 username:password>" http://server:8080/doveadm/v1
an example command would be
curl -H "Content-Type: application/json" -H "Authorization: Basic <base64 username:password>" -d '[["fetch",{"user":"username","field":["uid"],"query":["mailbox","INBOX"]},"c01"]]' http://server:8080/doveadm/v1
this should hopefully return something sensible, such as
[["doveadmResponse",[{"uid":"1"}],"c01"]]
Since the API is still a little beta, it will not return anything in case doveadm does not like the arguments (that is, calls i_fatal). Also, success is often indicated with 200 OK along with [["doveadmResponse",[],"c01"]].
We are going to improve the API in future release with v2, v1 is basically very analogous to using doveadm cli.
Aki
On 2016-04-04 20:22, aki.tuomi@dovecot.fi wrote:
A simple 1-line curl-example in the docs would do wonders :)
an example command would be
curl -H "Content-Type: application/json" -H "Authorization: Basic <base64 username:password>" -d '[["fetch",{"user":"username","field":["uid"],"query":["mailbox","INBOX"]},"c01"]]' http://server:8080/doveadm/v1
Awesome, I got it working with the API key. Thanks :)
participants (2)
-
aki.tuomi＠dovecot.fi
-
Tom Sommer