New feature: HTTP API

[aki.tuomi at dovecot.fi]

> On April 4, 2016 at 5:18 PM Tom Sommer <mail at tomsommer.dk> wrote:
> 
> 
> 
> On 2016-02-20 17:09, aki.tuomi at 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