# MUC Service Plugin

MUC Service is a plugin to manage the chat rooms over the REST/HTTP interface.
It is possible to get a XML based overview over all or filtered chat rooms and also to Create / Update / Delete chat rooms.

## Explanation of REST

To provide a standard way of accessing the data the MUC Service
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

## Chat room related REST Endpoints

### Basic HTTP Authentication

All REST Endpoint are secured by 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));
`

## GET /mucservice/chatrooms

Endpoint to get all chat rooms

Payload: none
Return value: Chatrooms

### Possible parameters

Parameter | Parameter Type | Description | Default value
--- | --- | --- | ---
servicename | @QueryParam | The name of the Group Chat Service | conference
type | @QueryParam | public: Only as List Room in Directory set rooms all: All rooms. | public
search | @QueryParam | Search/Filter by room name. This act like the wildcard search %String% |

### Examples

Header: Authorization: Basic YWRtaW46MTIzNDU=

GET http://example.org:9090/plugins/mucservice/chatrooms

GET http://example.org:9090/plugins/mucservice/chatrooms?type=all

GET http://example.org:9090/plugins/mucservice/chatrooms?type=all&servicename=privateconf

GET http://example.org:9090/plugins/mucservice/chatrooms?search=test

## GET /mucservice/chatrooms/{roomName}

Endpoint to get information over specific chat room

Payload: none
Return value: Chatroom

### Possible parameters

Parameter | Parameter Type | Description | Default value
--- | --- | --- | ---
roomname | @Path | Exact room name |
servicename | @QueryParam | The name of the Group Chat Service | conference

### Examples

Header: Authorization: Basic YWRtaW46MTIzNDU=

GET http://example.org:9090/plugins/mucservice/chatrooms/test

GET http://example.org:9090/plugins/mucservice/chatrooms/test?servicename=privateconf

## GET /mucservice/chatrooms/{roomName}/participants

Endpoint to get all participants with a role of specified room.

Payload: none
Return value: Participants

### Possible parameters

Parameter | Parameter Type | Description | Default value
--- | --- | --- | ---
roomname | @Path | Exact room name |
servicename | @QueryParam | The name of the Group Chat Service | conference

### Examples

Header: Authorization: Basic YWRtaW46MTIzNDU=

GET http://example.org:9090/plugins/mucservice/chatrooms/room1/participants

## POST /mucservice/chatrooms

Endpoint to create a new chat room.

Payload: Chatroom
Return value: void

### Possible parameters

Parameter | Parameter Type | Description | Default value
--- | --- | --- | ---
servicename | @QueryParam | The name of the Group Chat Service | conference

### Examples

Header: Authorization: Basic YWRtaW46MTIzNDU=

Header: Content-Type: application/xml

POST http://example.org:9090/plugins/mucservice/chatrooms

Payload:

        <chatRoom>
            <broadcastPresenceRoles>
                <broadcastPresenceRole>moderator</broadcastPresenceRole>
                <broadcastPresenceRole>participant</broadcastPresenceRole>
                <broadcastPresenceRole>visitor</broadcastPresenceRole>
            </broadcastPresenceRoles>
            <canAnyoneDiscoverJID>false</canAnyoneDiscoverJID>
            <canChangeNickname>false</canChangeNickname>
            <canOccupantsChangeSubject>false</canOccupantsChangeSubject>
            <canOccupantsInvite>false</canOccupantsInvite>
            <creationDate>2014-02-12T15:52:37.592+01:00</creationDate>
            <description>Global Chat Room</description>
            <logEnabled>true</logEnabled>
            <loginRestrictedToNickname>false</loginRestrictedToNickname>
            <maxUsers>0</maxUsers>
            <membersOnly>false</membersOnly>
            <moderated>false</moderated>
            <naturalName>global-1</naturalName>
            <owners>
                <owner>admin@localhost</owner>
            </owners>
            <password>test</password>
            <persistent>true</persistent>
            <publicRoom>true</publicRoom>
            <registrationEnabled>false</registrationEnabled>
            <roomName>global</roomName>
        </chatRoom>

## DELETE /mucservice/chatrooms/{roomName}

Endpoint to delete a chat room.

Payload: void
Return value: void

### Possible parameters

Parameter | Parameter Type | Description | Default value
--- | --- | --- | ---
roomname | @Path | Exact room name |
servicename | @QueryParam | The name of the Group Chat Service | conference

### Examples

Header: Authorization: Basic YWRtaW46MTIzNDU=

DELETE http://example.org:9090/plugins/mucservice/chatrooms/testroom

DELETE http://example.org:9090/plugins/mucservice/chatrooms/testroom?servicename=privateconf

## PUT /mucservice/chatrooms/{roomName}

Endpoint to update a chat room.

Payload: Chatroom
Return value: void

### Possible parameters

Parameter | Parameter Type | Description | Default value
--- | --- | --- | ---
roomname | @Path | Exact room name |
servicename | @QueryParam | The name of the Group Chat Service | conference

### Examples

Header: Authorization: Basic YWRtaW46MTIzNDU=

Header: Content-Type application/xml

PUT http://example.org:9090/plugins/mucservice/chatrooms/global

Payload:

        <chatRoom>
            <admins>
                <admin>admin@localhost</admin>
            </admins>
            <broadcastPresenceRoles/>
            <members>
                 <member>member1@localhost</member>
                 <member>member2@localhost</member>
            </members>
            <outcasts>
                <outcast>outcast1@localhost</outcast>
            </outcasts>
            <owners>
                <owner>owner@localhost</owner>
            </owners>
            <canAnyoneDiscoverJID>false</canAnyoneDiscoverJID>
            <canChangeNickname>false</canChangeNickname>
            <canOccupantsChangeSubject>false</canOccupantsChangeSubject>
            <canOccupantsInvite>false</canOccupantsInvite>
            <creationDate>2014-02-12T15:52:37.592+01:00</creationDate>
            <description>Global Chat Room edit</description>
            <logEnabled>true</logEnabled>
            <loginRestrictedToNickname>false</loginRestrictedToNickname>
            <maxUsers>0</maxUsers>
            <membersOnly>false</membersOnly>
            <moderated>false</moderated>
            <naturalName>global-2</naturalName>
            <password>test</password>
            <persistent>true</persistent>
            <publicRoom>true</publicRoom>
            <registrationEnabled>false</registrationEnabled>
            <roomName>global</roomName>
        </chatRoom>