Usage
This is a simple REST-like API over HTTP(s) protocol.
Objects are located in a hierarchical namespace and identified by a unique URI.
Structure
An object is identified by a URI in the namespace. Each object can be either a file or a directory.
The last element of a URI provides the name of the object
A directory is a collection of objects
A file is a list of key/value parameters
Example of an object returning a list of key/value parameters:
{
"key1": "value1",
"key2": "value2",
...
}
Example of an object returning a list of objects:
{
"object1",
"object2",
...
}
Input / Output
Both input and output are always text, encoded in the US-ASCII character set.
Input
One advantage of using JSON is the ability to use the exact JSON output as an input, thus allowing convenient manipulation of objects.
The JSON format is specified in RFC 4627.
Input is formatted as a JSON object. Keys are always string and values can be either string or null.
Example of possible values:
{
"key1": "value",
"key5": null,
...
}
The following HTTP header field must be specified in the request POST
and PUT
request when sending a JSON file:
Content-Type: application/json
Equivalence
The following table gives the equivalence between JSON, HTTP query and low-level alohactl
tool formats:
JSON | alohactl |
---|---|
"key": "value" |
|
"key": null |
|
"key": true |
For example, the following JSON input:
{
"protocol": "http",
"log": "enabled",
"log_format": "http",
"default_farm": "bk_myappli"
}
Output
Output is always formatted as JSON, it can be either a single object or an array of string.
The following HTTP header is set in the response:
Content-Type: application/json
JSON array
A directory returns an array containing the names of the objects it owns.
{
"object1",
"object2",
...
}
JSON object
The JSON object output format is identical to the JSON input format, so that the output from an object can be used directly as an input for another object of the same family.
However, an output of a JSON object can also contain the value true
.
For a description of the JSON object format, read section about JSON input.
Text
Some files return plain text, encoded in the US-ASCII character set.
In this case, the following HTTP header field is set in the response:
Content-Type: text/plain
Specific parameters
Some parameters have specific meanings. They are written in uppercase letters. They are only used with a few HTTP methods and can sometime depend on another parameter.
Parameter | Value | Method | Depends on | Description |
---|---|---|---|---|
DEFAULT | a template |
| nothing | Specify a default template |
METHOD | "clone" |
|
| Specify a special sub-method to call |
SOURCE | an object |
|
| Specify an object to clone from |
URI
All URIs must start by the string /api/X/
where X
indicates the version of the API.
If you don't know X
, you can call /api
which returns an array of supported API versions.
GET /api
[
"2"
]
HTTP Methods
Each object can understand up to four methods:
| display (returns a JSON object, a JSON array or plain text) |
| create (requires a JSON object) |
| update (requires a JSON object) |
| delete |
When available, PUT
accepts exactly the same format as POST
but can accept a partial content.
Authentication
Each command requires an HTTP Basic Authentication, as described in RFC 2616.
An HTTP Basic Authentication appears as an HTTP header in the form:
Authorization: Basic YWRtaW46YWRtaW4=
Authentication is only permitted for the user admin with the password specified in /etc/passwd
.
It is the same password used to connect to the GUI and the CLI.
An authentication failure returns the following HTTP headers:
Status: 401 Unauthorized
WWW-Authenticate: Basic realm="aloha"
Document convention
Most JSON API calls must be run in a scope or in a transaction.
In the URL example provided below, scope
and trans
keywords as well as <scopename>
and <transactionid>
are replaced by the character *
.
Information
URI | HTTP method | Action |
---|---|---|
|
| API version |
Scopes
A
scope
is a portion of the configuration.It is identified by a name composed by alpha-numeric characters.
A specific scope name is reserved:
root
. It can access any configuration which stands outside of a scope.
There is no way to list existing scopes through alohactl2
command.
In a HAProxy configuration, a scope is identified by a begin
and end
tags.
All the frontends and backends between these tags are prefixed by the scope name.
The HAProxy configuration for a scope called bob:
defaults bob:l7_begin
frontend bob:newservice
# ...
default_backend bob:newfarm
backend bob:newfarm
# ...
defaults bob:l7_end
Create a scope
To create a scope, apply configuration either atomically or through a transaction to a new scope name.
Delete a scope
To delete a scope, remove all configuration belonging to the scope.
Transactions
Transactions allow multiple configuration changes in one atomic operation.
Each transaction is identified by a unique identifier composed by alphanumeric characters.
Example: BrwClcc76t.
Each request can be executed either atomically or as part of a transaction
Both atomic requests and transactions apply only on a single scope
An atomic request immediately applies the changes to the files
A transaction must be started before issuing a bunch of requests, then it can be either committed or canceled
Canceling a transaction makes no change on files and drops the entire bunch of requests since the beginning of the transaction
Committing a transaction consecutively applies the changes to the files for the entire bunch of requests since the beginning of the transaction
URI | HTTP method | Action |
---|---|---|
|
| list all |
|
| create |
|
| commit |
| cancel | |
| cf command | run an atomic command in a scope |
| cf command | run an atomic command in a transaction |
where:
| scope identifier |
| transaction unique identifier |
| actions to perform |
When committing a transaction, the following steps happen:
Re-creates working context from current configuration
Re-plays all update actions recorded on transaction identified by on newly re-created context
Then, 2 options:
If re-play is successful: configuration is locked, validate, applied and finally unlocked
If error occurs during locked phase, it processes a configuration rollback and lock is removed
L7 Farms
URI | HTTP method | Action |
---|---|---|
|
| list all |
| delete all | |
|
| show configuration |
| create | |
| update | |
| delete |
where:
| name of a L7 farm |
L7 Servers
URI | HTTP method | Action |
---|---|---|
|
| list all |
| delete all | |
|
| show configuration |
| create | |
| update | |
| delete |
where:
| name of a L7 farm |
| name of a L7 server |
L7 Services
URI | HTTP method | Action |
---|---|---|
|
| list all |
| delete all | |
|
| show configuration |
| create | |
| update | |
| delete |
where:
| name of an L7 service |
L7 Listeners
URI | HTTP method | Action |
---|---|---|
|
| list all |
| delete all | |
|
| show configuration |
| create | |
| update | |
| delete |
where:
| name of a L7 service |
| name of a L7 listener |
L7 Rules
URI | HTTP method | Action |
---|---|---|
|
| list all |
| delete all | |
|
| show configuration |
| create | |
| update | |
| delete |
The <objecttype>
can be either:
| if the rule applies to a L7 service |
| if the rule applies to a L7 farm |
| name of the object to apply the action on |
| depends on |
The following are rules available for a service
:
tcpreqconn
, with the following<attribute>
list:L7 tcpreqconn rule attributes
tcpreqcont
, with the following<attribute>
list:L7 tcpreqcont rule attributes
httpreq
, with the following<attribute>
list:L7 httpreq rule parameters
redirect
, with the following<attribute>
list:L7 redirect rule parameters
usefarm
, with the following<attribute>
list:L7 usefarm rule parameters
The following are rules available for a farm:
tcpreqcont
, with the following<attribute>
list:L7 tcpreqcont rule attributes
httpreq
, with the following<attribute>
list:L7 httpreq rule parameters
redirect
, with the following<attribute>
list:L7 redirect rule parameters
useserver
, with the following<attribute>
list:L7 useserver rule parameters
tcprspcont
, with the following<attribute> `list: :code:`L7 tcprspcont rule parameters
tcpcheck
, with the following<attribute>
list:L7 tcpcheck rule parameters
A <number>
can be either:
| get the first rule of the list |
| get the last rule of the list |
a positive integer | get the rule pointed by the integer |
When deleting a rule, the following applies:
to delete the latest rule of the list, set
<number>
totail
to delete the first rule of the list, set
<number>
to either1
orhead
to delete the Xth rule, set
<number>
toX
When creating a new rule, the following applies:
to add a rule at the bottom of the list, set
<number>
totail
to add a rule at the top of the list, set
<number>
to either1
orhead
to insert a rule before Xth one, set
<number>
toX
L4 Farms
URI | HTTP method | Action |
---|---|---|
|
| list all |
| delete all | |
|
| show configuration |
| create | |
| update | |
| delete |
where:
| name of a L4 farm |
L4 Servers
URI | HTTP method | Action |
---|---|---|
|
| list all |
| delete all | |
|
| show configuration |
| create | |
| update | |
| delete |
where:
| name of a L4 farm |
| name of a L4 server |
System
URI | HTTP method | Action |
---|---|---|
|
| Save local configuration |
|
| Tell a peer to save its configuration |
|
| Push local configuration to the peer |
Examples Using Curl
CURL (curl
) is a simple Linux command line tool that can be used to run requests on the HAProxy Enterprise or HAProxy ALOHA API.
Main curl options
The following options are required when manipulating the API using curl:
CURL option | Description |
---|---|
| Send the specified data in a POST or PUT request using the content-type application/x-www-form-urlen-coded. Prefix |
| Write the HTTP headers to the specified file. use |
| Add custom HTTP headers to the request |
| Do not perform SSL server certificate validation. |
| Send HTTP Basic authentication credentials |
| Specify the HTTP method to use for the request |
The following is a minimum curl request:
$ curl -k -u admin:admin https://10.0.0.1:4444/api
The following is a minimum POST request to create a new L7 farm:
$ curl -X POST -H "Content-Type: application/json" -d @/tmp/content.txt -k --user admin:admin https://10.0.0.3:4444/api/2/scope/root/l7/farm/newfarm
Complete example over a transaction
This example creates a new frontend ft_web which points to a new backend bk_web in scope root
using the API, as shown in the following procedure:
Create the backend.
Add srv1 to the backend.
Add srv2 to the backend.
Create the frontend.
Add a listener to the frontend.
There are two options:
using the atomic method: the configuration is updated and applied, and HAProxy is reloaded after each step.
using a transaction: a single configuration update is processed; HAProxy is reloaded only once.
-
Create a new transaction in the scope root:
$ $CURL https://10.0.0.3:4444/api/2/scope/root/trans 78hm4ySMm0
-
Create the back end bk_web:
-
First, create a file
/tmp/content.txt
with the JSON parameters necessary:{ "balance": "roundrobin", "protocol": "http", "log": "enabled", "log_format": "http", "http_connection_mode": null, "http_pretend_keepalive": null, "http_xff_header_insert": "enabled", "http_cookie": "enabled", "http_cookie_name": "bkweb", "http_cookie_mode": "set-silent", "http_cookie_nocache": "enabled", "check_interval": "3", "check_rise": "2", "check_fall": "3", "check_port": null, "check_timeout": null, "adv_check": "http", "adv_check_http_method": "HEAD", "adv_check_http_uri": "/", "queued_timeout": null, "connect_timeout": "4", "connect_retries": null, "connect_failure_redispatch": null, "connect_source": null, "connect_transparent": null, "server_inactivity_timeout": "25", "tcpreq_inspect_delay": null, "tcprsp_inspect_delay": null }
-
Next, create the L7 farm:
$ $CURL -X POST -d @/tmp/content.txt -H "Content-Type: application/json" https://10.0.0.3:4444/api/2/trans/78hm4ySMm0/l7/farm/bk_web
-
-
Add srv1 in the back end:
-
First, create a file /tmp/content.txt with the JSON parameters necessary:
{ "address": "192.168.1.21", "port": "80", "max_connections": "1000", "weight": "10", "http_cookie_id": "srv1", "sorry": null, "check": "enabled", "maintenance": null, "ssl": null }
-
Next, create the server in bk_web L7 farm:
$ $CURL -X POST -d @/tmp/content.txt -H "Content-Type: application/json" https://10.0.0.3:4444/api/2/trans/78hm4ySMm0/l7/farm/bk_web/server/srv1
-
-
Add srv2 in the back end:
-
First, create a file
/tmp/content.txt
with the JSON parameters necessary:{ "address": "192.168.1.22", "port": "80", "max_connections": "1000", "weight": "10", "http_cookie_id": "srv2", "sorry": null, "check": "enabled", "maintenance": null, "ssl": null }
-
Next, create the server in bk_web L7 farm:
$ $CURL -X POST -d @/tmp/content.txt -H "Content-Type: application/json" https://10.0.0.3:4444/api/2/trans/78hm4ySMm0/l7/farm/bk_web/server/srv2
-
-
Create the service ft_web:
-
First, create a file
/tmp/content.txt
with the JSON parameters necessary:{ "protocol": "http", "log": "enabled", "log_format": "http", "log_ignore_null": null, "http_connection_mode": null, "http_pretend_keepalive": null, "client_inactivity_timeout": "25", "http_request_timeout": null, "http_keepalive_timeout": null, "max_connections": "1000", "default_farm": "bk_web", "tcpreq_inspect_delay": null }
-
Next, create the L7 service:
$ $CURL -X POST -d @/tmp/content.txt -H "Content-Type: application/json" https://10.0.0.3:4444/api/2/trans/78hm4ySMm0/l7/service/ft_web
-
-
Create the listener for the L7 service:
-
First, create a file /tmp/content.txt with the JSON parameters necessary:
{ "port": "80", "address": "0.0.0.0", "transparent": null, "ssl": null, "ssl_certificate": null }
-
Next, create the listener for the L7 service:
$ $CURL -X POST -d @/tmp/content.txt -H "Content-Type: application/json" https://10.0.0.3:4444/api/2/trans/78hm4ySMm0/l7/service/ft_web/listener/http
-
-
Commit the transaction:
$ $CURL -X POST https://10.0.0.3:4444/api/2/trans/78hm4ySMm0
Save the configuration in a cluster
In the examples below, we consider that the CURL string is equivalent to curl -k -D - --user admin:admin
.
-
Save the configuration on the master:
$ $CURL -X POST https://10.0.0.3:4444/api/2/sys/local/save
-
Push the master's configuration to the slave:
$ $CURL -X POST https://10.0.0.3:4444/api/2/sys/peers/0/push
-
Through the master, tell the slave to save its configuration:
$ $CURL -X POST https://10.0.0.3:4444/api/2/sys/peers/0/save
Next up
REST/JSON Error Codes