# 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

        <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>