# MUC Service Plugin Readme

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 and there user roles.

## Installation

Copy the file, “mucservice.jar” into the plugins directory of your Openfire installation. The plugin will then be automatically deployed.

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

## 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));
`

## Data types

### Chatroom

Parameter | Optional | Description
--- | --- | ---
roomName | No | The name/id of the room. Can only contains lowercase and alphanumeric characters.
naturalName | No | Also the name of the room, but can contains non alphanumeric characters. It’s mainly used for users while discovering rooms hosted by the Multi-User Chat service.
description | No | Description text of the room.
password | Yes | The password that the user must provide to enter the room
creationDate | Yes | The date when the room was created. Will be automatically set by creation. Example: 2014-07-10T09:49:12.411+02:00
modificationDate | Yes | The last date when the room’s configuration was modified. If the room’s configuration was never modified then the initial value will be the same as the creation date. Will be automatically set by update. Example: 2014-07-10T09:49:12.411+02:00
maxUsers | Yes | the maximum number of occupants that can be simultaneously in the room. 0 means unlimited number of occupants.
persistent | Yes | Can be “true” or “false”. Persistent rooms are saved to the database to make their configurations persistent together with the affiliation of the users. Otherwise the room will be destroyed if the last occupant leave the room.
publicRoom | Yes | Can be “true” or “false”. True if the room is searchable and visible through service discovery.
registrationEnabled | Yes | Can be “true” or “false”. True if users are allowed to register with the room. By default, room registration is enabled.
canAnyoneDiscoverJID | Yes | Can be “true” or “false”. True if every presence packet will include the JID of every occupant.
canOccupantsChangeSubject | Yes | Can be “true” or “false”. True if participants are allowed to change the room’s subject.
canOccupantsInvite | Yes | Can be “true” or “false”. True if occupants can invite other users to the room. If the room does not require an invitation to enter (i.e. is not members-only) then any occupant can send invitations. On the other hand, if the room is members-only and occupants cannot send invitation then only the room owners and admins are allowed to send invitations.
canChangeNickname | Yes | Can be “true” or “false”. True if room occupants are allowed to change their nicknames in the room. By default, occupants are allowed to change their nicknames.
logEnabled | Yes | Can be “true” or “false”. True if the room’s conversation is being logged. If logging is activated the room conversation will be saved to the database every couple of minutes. The saving frequency is the same for all the rooms and can be configured by changing the property “xmpp.muc.tasks.log.timeout”.
loginRestrictedToNickname | Yes | Can be “true” or “false”. True if registered users can only join the room using their registered nickname. By default, registered users can join the room using any nickname.
membersOnly | Yes | Can be “true” or “false”. True if the room requires an invitation to enter. That is if the room is members-only.
moderated | Yes | Can be “true” or “false”. True if the room in which only those with “voice” may send messages to all occupants.
broadcastPresenceRoles | Yes | The list of roles of which presence will be broadcasted to the rest of the occupants.
owners | Yes | A collection with the current list of owners. The collection contains the bareJID of the users with owner affiliation.
admins | Yes | A collection with the current list of admins. The collection contains the bareJID of the users with admin affiliation.
members | Yes | A collection with the current list of room members. The collection contains the bareJID of the users with member affiliation. If the room is not members-only then the list will contain the users that registered with the room and therefore they may have reserved a nickname.
outcasts | Yes | A collection with the current list of outcast users. An outcast user is not allowed to join the room again. The collection contains the bareJID of the users with outcast affiliation.

# Chat room related REST Endpoints

## 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: HTTP status 201 (Created)

### 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 Example 1 (required parameters):

    <chatRoom>
        <naturalName>global-1</naturalName>
        <roomName>global</roomName>
        <description>Global Chat Room</description>
    </chatRoom>

Payload Example 2 (available parameters):

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

## DELETE /mucservice/chatrooms/{roomName}

Endpoint to delete a chat room.

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

### 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: HTTP status 200 (OK)

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

## POST /mucservice/chatrooms/{roomName}/{roles}/{jid}

Endpoint to add a new user role to a room.

Payload: none
Return value: HTTP status 201 (Created)

### Possible parameters

Parameter | Parameter Type | Description | Default value
--- | --- | --- | ---
roomname | @Path | Exact room name |
jid | @Path | JID of the owner (username@xmppDomain) |
roles | @Path | Available roles: owners admins members outcasts |
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/global/owners/owner@localhost

POST http://example.org:9090/plugins/mucservice/chatrooms/global/admins/admin@localhost

POST http://example.org:9090/plugins/mucservice/chatrooms/global/members/member@localhost

POST http://example.org:9090/plugins/mucservice/chatrooms/global/outcasts/outcast@localhost

POST http://example.org:9090/plugins/mucservice/chatrooms/global/owners/owner@localhost?servicename=privateconf

## DELETE /mucservice/chatrooms/{roomName}/{roles}/{jid}

Endpoint to remove a room user role.

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

### Possible parameters

Parameter | Parameter Type | Description | Default value
--- | --- | --- | ---
roomname | @Path | Exact room name |
jid | @Path | JID of the owner (username@xmppDomain) |
roles | @Path | Available roles: owners admins members outcasts |
servicename | @QueryParam | The name of the Group Chat Service | conference

### Examples

Header: Authorization: Basic YWRtaW46MTIzNDU=

Header: Content-Type application/xml

DELETE http://example.org:9090/plugins/mucservice/chatrooms/global/owners/owner@localhost

DELETE http://example.org:9090/plugins/mucservice/chatrooms/global/admins/admin@localhost

DELETE http://example.org:9090/plugins/mucservice/chatrooms/global/members/member@localhost

DELETE http://example.org:9090/plugins/mucservice/chatrooms/global/outcasts/outcast@localhost

DELETE http://example.org:9090/plugins/mucservice/chatrooms/global/owners/owner@localhost?servicename=privateconf