Using the REST Interface

When using the REST interface, note the following common principles:

Namespaces

Currently vWAF supports the following namespaces:

  • /api/admin_20110601

    Used in versions prior to version 4.6.

  • /api/af/2.0

    The current implementation.

  • /api/af/1.x

    Previous implementation. You can use previous versions without having to change your existing scripts (seeForward Compatibility).

    Please be aware that you should not add, edit, or remove applications with this obsolete interface anymore. This might give you unexpected results with application mapping. Instead, use the new /api/af/2.0 interface.

  • /api/common/0.9

    A collection of additional functions; currently only used for session-based login.

Each namespace consists of the following elements:

  • Objects

    An object is any resource that can be manipulated, such as a user, a license, or an application. With most objects, you can perform the following actions:

    • retrieve the data of the object
    • update the object
    • create a new object
    • delete the object

  • Collections

    A collection is a group of similar objects, such as a collection of all users, or a collection of all applications.

  • Directories

    A directory is a node within the namespace, collecting particular objects and collections. Directories are mainly used to simplify navigation.

Each node within the namespace consists of data plus a number of attributes. To distinguish the attributes from data, all attributes begin with two underscores (__).

Encoding

The current version only supports JSON encoding for both input and output. Later versions will also support XML encoding and will use the Content Type header to select the encoding.

Response

On success, the interface returns a 2xx HTTP status code (currently only 200).

On failure, the interface responds with a non-2xx HTTP status code. For a list of codes, see HTTP Error Codes.

The topmost component of a response is always a dictionary. A value may be None or null, which means that this value is unknown.

Example

A typical request looks like this:

In this documentation, all requests are sent via the command line tool cURL.

$ curl -u admin:admin -v http://localhost:8087/api/af > GET /api/af HTTP/1.1 > Authorization: Basic YWRtaW46YWRtaW4= > User-Agent: curl/7.21.4 (universal-apple-darwin11.0) libcurl/7.21.4 OpenSSL/0.9.8r zlib/1.2.5 > Host: localhost:8087 > Accept: */* > < HTTP/1.1 200 OK < Transfer-Encoding: chunked < Date: Mon, 17 Sep 2012 11:49:35 GMT < Server: localhost < {    "__name": "af",    "__path": "/api/af/",    "__subnodes": [        "1.0",        "latest"    ] }

Lines beginning with a right angle bracket (>) state the HTTP request header. Lines beginning with a left angle bracket (<) state the HTTP response header.

The actual data follow the response header in the form of a dictionary with the attributes:

  • __name (the name of the node)
  • __path (the full path to the node)
  • __subnodes (list of all subnodes)

The node /api/af, for example, contains the two subnodes 1.0 and latest.

Standard authentication

Each request within the namespace /api/af needs authentication. Currently, the REST interface supports:

  • request-based authentication with HTTP basic auth
  • session-based authentication

With request-based authentication (HTTP basic auth), you send the username and password of a valid user along with each request. This is the preferred method for single requests or single scripts.

With session-based authentication, you perform one single log-in call. As a result, vWAF returns a session ID and sets a cookie. This cookie must be sent along with all subsequent requests. This is the preferred method for interactive programs, such as a special GUI that uses the REST interface.

ATTENTION
If the user whose credentials you use for authentication has limited rights due to his or her user group, the same limitations apply to your access via the REST interface.

The URL for session-based login is /api/common/0.9/login.

You perform the login by sending the username and password (JSON encoded) to the login URL. As a result, vWAF sets the cookie and returns the cookie name and the cookie value in the response.

Example

$ curl -v -H 'Content-Type: application/json' --data '{"username": "admin", "password": "admin"}' http://127.0.0.1:8087/api/common/0.9/login > POST /api/common/0.9/login HTTP/1.1 > User-Agent: curl/7.21.4 (universal-apple-darwin11.0) libcurl/7.21.4 OpenSSL/0.9.8r zlib/1.2.5 > Host: 127.0.0.1:8087 > Accept: */* > Content-Type: application/json > Content-Length: 42 > < HTTP/1.1 200 OK < Set-Cookie: SESSIONID=ae92ae259fbf10b5c01759251795029f; Path=/ < Transfer-Encoding: chunked < Date: Mon, 17 Sep 2012 16:10:05 GMT < Server: localhost < {    "session_id": "ae92ae259fbf10b5c01759251795029f",    "session_key": "SESSIONID" }

Now you can send additional requests with the help of the cookie:

$ curl -v -H 'Cookie: SESSIONID=ae92ae259fbf10b5c01759251795029f' http://127.0.0.1:8087/api/af/2.0/auth/users > GET /api/af/2.0/auth/users HTTP/1.1 > User-Agent: curl/7.21.4 (universal-apple-darwin11.0) libcurl/7.21.4 OpenSSL/0.9.8r zlib/1.2.5 > Host: 127.0.0.1:8087 > Accept: */* > Cookie: SESSIONID=ae92ae259fbf10b5c01759251795029f > < HTTP/1.1 200 OK < Transfer-Encoding: chunked < Date: Mon, 17 Sep 2012 16:10:55 GMT < Server: localhost < {    "__name": "users",    "__path": "/api/af/2.0/auth/users/",    "__subnodes": [        "admin"    ],    "users": [        "admin"    ] }

Authentication with cluster password

If you access the REST API via localhost, you can also use an empty username and the cluster password for authentication.

You can find the cluster password in the variable clusterPwd in the configuration file zeusafm.conf.

The advantage of this method is that you don’t have to add an additional user just for login via the REST interface.

ATTENTION
This method only works locally when accessing the REST API via localhost or ::1).

In addition, this method only works if the option aod-magic-authenticate- with-cluster-password has been added and set to True in the configuration file zeusafm.conf.

The permissions granted after authentication are the same as for users of the user group zeusafm Admin.

Example

The following request performs the login, presuming that the cluster password is “NdY9kXEmKED7ELhnZqt9hWS8” and that aod-magic-authenticate-with-cluster-password has been set to True in the configuration file zeusafm.conf.

$ curl -u :NdY9kXEmKED7ELhnZqt9hWS8 http://127.0.0.1:8087/api/af/latest/ping {    "__name": "ping",    "__path": "/api/af/latest/ping/",    "__subnodes": [] }

Getting the data of an object

To retrieve the data of an object, you use the HTTP GET method.

Example

The following request retrieves the user data of the user “admin”.

$ curl -v -u admin:admin  http://localhost:8087/api/af/2.0/auth/users/admin > GET /api/af/2.0/auth/users/admin HTTP/1.1 > Authorization: Basic YWRtaW46YWRtaW4= > User-Agent: curl/7.21.4 (universal-apple-darwin11.0) libcurl/7.21.4 OpenSSL/0.9.8r zlib/1.2.5 > Host: localhost:8087 > Accept: */* > < HTTP/1.1 200 OK < Transfer-Encoding: chunked < Date: Mon, 17 Sep 2012 16:16:40 GMT < Server: localhost < {    "__name": "admin",    "__path": "/api/af/2.0/auth/users/admin/",    "__subnodes": [],    "email": "",    "enabled": true,    "fullname": "Administrator",    "groups": [        "master_admin"    ],    "last_failed_login": 0,    "last_login": 1347898205,    "username": "admin" }

Adding an object

To create a new object, you send the object’s data to the corresponding collection with a POST request.

Example

To add a new user, you need to send the username (plus additional attributes if you like) to /api/af/2.0/auth/users. The following request adds a new user named “auditor”.

$ curl -v -u admin:admin -H "Content-Type: application/json" --data '{"username": "auditor"}' http://localhost:8087/api/af/2.0/auth/users > POST /api/af/2.0/auth/users HTTP/1.1 > Authorization: Basic YWRtaW46YWRtaW4= > User-Agent: curl/7.21.4 (universal-apple-darwin11.0) libcurl/7.21.4 OpenSSL/0.9.8r zlib/1.2.5 > Host: localhost:8087 > Accept: */* > Content-Type: application/json > Content-Length: 23 > < HTTP/1.1 200 OK < Transfer-Encoding: chunked < Date: Mon, 17 Sep 2012 16:19:40 GMT < Server: localhost < {    "__name": "auditor",    "__path": "/api/af/2.0/auth/users/auditor/",    "__subnodes": [],    "email": "",    "enabled": true,    "fullname": "",    "groups": [],    "last_failed_login": 0,    "last_login": 0,    "username": "auditor" }

vWAF answers with the contents of the created object. The attribute __name states the name of the created object. In this case, this name is identical with the username.

In other cases, for example with licenses and applications, vWAF returns an internal UUID that’s unique within the whole cluster.

Changing an object

To change an object, you send new values to this object. You use a PUT request for this. For compatibility reasons, you can also use POST.

In both cases it’s important that the target of the operation is the object itself. Fields that you don’t provide remain unchanged.

Example

The following request changes the field “fullname”.

$ curl -v -u admin:admin -X PUT -H "Content-Type: application/json" --data '{"fullname": "Audit User"}' http://localhost:8087/api/af/2.0/auth/users/auditor > POST /api/af/2.0/auth/users/auditor HTTP/1.1 > Authorization: Basic YWRtaW46YWRtaW4= > User-Agent: curl/7.21.4 (universal-apple-darwin11.0) libcurl/7.21.4 OpenSSL/0.9.8r zlib/1.2.5 > Host: localhost:8087 > Accept: */* > Content-Type: application/json > Content-Length: 26 > < HTTP/1.1 200 OK < Transfer-Encoding: chunked < Date: Mon, 17 Sep 2012 16:23:55 GMT < Server: localhost < {    "__name": "auditor",    "__path": "/api/af/2.0/auth/users/auditor/",    "__subnodes": [],    "email": "",    "enabled": true,    "fullname": "Audit User",    "groups": [],    "last_failed_login": 0,    "last_login": 0,    "username": "auditor" }

Similar to creating an object, vWAF answers with the contents of the changed object. The attribute __name states the name of the changed object. In this case, this name is identical with the username.

In other cases, for example with licenses and applications, vWAF returns an internal UUID that’s unique within the whole cluster.

Deleting an object

To delete an object, you use the DELETE method.

When successful, vWAF answers with an empty object.

Example

The following request deletes the user “auditor”.

$ curl -v -u admin:admin  -X DELETE http://localhost:8087/api/af/2.0/auth/users/auditor > DELETE /api/af/2.0/auth/users/auditor HTTP/1.1 > Authorization: Basic YWRtaW46YWRtaW4= > User-Agent: curl/7.21.4 (universal-apple-darwin11.0) libcurl/7.21.4 OpenSSL/0.9.8r zlib/1.2.5 > Host: localhost:8087 > Accept: */* > < HTTP/1.1 200 OK < Transfer-Encoding: chunked < Date: Mon, 17 Sep 2012 16:28:56 GMT < Server: localhost < {}