# 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

- Get overview over all or specific system properties and to create, update or delete system property

## 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"/>