REST API Plugin Readme

The REST API Plugin provides the ability to manage system properties by sending an HTTP request to the server. This plugin’s functionality is useful for applications that need to administer Openfire outside of the Openfire admin console.


Feature list

Installation

Copy restAPI.jar into the plugins directory of your Openfire server. The plugin will then be automatically deployed. To upgrade to a new version, copy the new restAPI.jar file over the existing file.

Explanation of REST

To provide a standard way of accessing the data the plugin is using REST.

HTTP Method Usage
GET Receive a read-only data
PUT Overwrite an existing resource
POST Creates a new resource
DELETE Deletes the given resource

Authentication

All REST Endpoint are secured by Basic HTTP Authentication or by shared secret key. The configuration can be done in Openfire Admin console under Server > Server Settings > REST API.

Basic HTTP Authentication

To access the endpoints is that required to send the Username and Password of a Openfire Admin account in your header request.

E.g. Header: Authorization: Basic YWRtaW46MTIzNDU= (username: admin / password: 12345)

Example for Jersey Client

Client c = Client.create();
c.addFilter(new HTTPBasicAuthFilter(user, password));

Shared secret key

To access the endpoints is that required to send the secret key in your header request. The secret key can be defined in Openfire Admin console under Server > Server Settings > REST API.

E.g. Header: Authorization: s3cretKey

Data types

System Property

Parameter Optional Description
key No The name of the system property
value No The value of the system property

System related REST Endpoints

GET /restapi/system/properties

Endpoint to get all system properties

Payload: none
Return value: System properties

Examples

Header: Authorization: Basic YWRtaW46MTIzNDU=

GET http://example.org:9090/plugins/restapi/system/properties

GET /restapi/system/properties/{propertyName}

Endpoint to get information over specific system property

Payload: none
Return value: System property

Possible parameters

Parameter Parameter Type Description Default value
propertyName @Path The name of system property

Examples

Header: Authorization: Basic YWRtaW46MTIzNDU=

GET http://example.org:9090/plugins/restapi/system/properties/xmpp.domain

POST /restapi/system/properties

Endpoint to create a system property

Payload: System Property
Return value: HTTP status 201 (Created)

Examples

Header: Authorization: Basic YWRtaW46MTIzNDU=
Header: Content-Type: application/xml

POST http://example.org:9090/plugins/restapi/system/properties

Payload Example:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<property key="propertyName" value="propertyValue"/>

DELETE /restapi/system/properties/{propertyName}

Endpoint to delete a system property

Payload: none
Return value: HTTP status 200 (OK)

Possible parameters

Parameter Parameter Type Description Default value
propertyName @Path The name of system property

Examples

Header: Authorization: Basic YWRtaW46MTIzNDU=

DELETE http://example.org:9090/plugins/restapi/system/properties/propertyName

PUT /restapi/system/properties/{propertyName}

Endpoint to update / overwrite a system property

Payload: System property
Return value: HTTP status 200 (OK)

Possible parameters

Parameter Parameter Type Description Default value
propertyName @Path The name of system property

Examples

Header: Authorization: Basic YWRtaW46MTIzNDU=
Header: Content-Type application/xml

PUT http://example.org:9090/plugins/restapi/system/properties/propertyName

Payload:

<<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<property key="propertyName" value="anotherValue"/>