REST API Client

REST API Client is an Java based Client for the Openfire REST API Plugin which provides the ability to manage Openfire instance by sending an REST/HTTP request to the server.

Repository

The project is available through the central Maven Repository

Maven

<dependency>
    <groupId>org.igniterealtime</groupId>
    <artifactId>rest-api-client</artifactId>
    <version>1.1.5</version>
</dependency>

Gradle / Grails

compile 'org.igniterealtime:rest-api-client:1.1.5'

Dependencies

The REST API plugin need to be installed and configured on the Openfire server.

• How to install REST API
• How to configure REST API

Examples

Authentication

REST API Plugin provides two types of authentication.

• Basic HTTP Authentication
• Shared secret key

  // Basic HTTP Authentication
  AuthenticationToken authenticationToken = new AuthenticationToken("admin", "testPassword");

  // Shared secret key
  AuthenticationToken authenticationToken = new AuthenticationToken("FQaCIpmRNBq4CfF8");

Data serialization

REST API Plugin provides both JSON and XML serialization.

  // By default XML will be used for serialization; setting the 'Accept: application/xml' 'Content-Type: application/xml' headers
  RestApiClient restApiClient = new RestApiClient("http://testdomain.com", 9090, authenticationToken);

  // Similarily JSON can set for serialization; setting the 'Accept: application/json' 'Content-Type: application/json' headers
  RestApiClient restApiClient = new RestApiClient("http://testdomain.com", 9090, authenticationToken, SupportedMediaType.JSON);

User related examples

  // Set Shared secret key
  AuthenticationToken authenticationToken = new AuthenticationToken("FQaCIpmRNBq4CfF8");
  
  // Set Openfire settings (9090 is the port of Openfire Admin Console)
  RestApiClient restApiClient = new RestApiClient("http://testdomain.com", 9090, authenticationToken);

  // Request all available users
  restApiClient.getUsers();

  // Get specific user by username
  restApiClient.getUser("testUsername");

  // Search for the user with the username "test". This act like the wildcard search %String%
  HashMap<String, String> querys = new HashMap<String, String>();
  querys.put("search", "test");
  restApiClient.getUsers(querys);

  // Create a new user (username, name, email, password). There are more user settings available.
  UserEntity userEntity = new UserEntity("testUsername", "testName", "test@email.com", "p4ssw0rd");
  restApiClient.createUser(userEntity);

  // Update a user
  userEntity.setName("newName");
  restApiClient.updateUser(userEntity);

  // Delete a user
  restApiClient.deleteUser("testUsername");

  // Get all user groups from a user
  restApiClient.getUserGroups("testUsername");

  // Add user to groups
  List<String> groupNames = new ArrayList<String>();
  groupNames.add("Moderators");
  groupNames.add("Supporters");
  UserGroupsEntity userGroupsEntity = new UserGroupsEntity(groupNames);
  restApiClient.addUserToGroups("testUsername", userGroupsEntity);
  
  // Add user to group
  restApiClient.addUserToGroup("testUsername", "Moderators");
  
  // Delete user from a group
  restApiClient.deleteUserFromGroup("testUsername", "Moderators");

  // Lockout/Ban a user
  restApiClient.lockoutUser("testUsername");

  // Unlock/Unban a user
  restApiClient.unlockUser("testUsername");

Chat rooms related examples

  // Set Shared secret key
  AuthenticationToken authenticationToken = new AuthenticationToken("FQaCIpmRNBq4CfF8");
  // Set Openfire settings (9090 is the port of Openfire Admin Console)
  RestApiClient restApiClient = new RestApiClient("http://testdomain.com", 9090, authenticationToken);

  // Request all public chatrooms
  restApiClient.getChatRooms();

  // Search for the chat room with the room name "test". This act like the wildcard search %String%
  HashMap<String, String> querys = new HashMap<String, String>();
  querys.put("search", "test");
  restApiClient.getChatRooms(querys);

  // Create a new chat room (chatroom id, chatroom name, description). There are more chatroom settings available.
  MUCRoomEntity chatRoom = new MUCRoomEntity("chatroom1", "First Chat Room", "Some description");
  restApiClient.createChatRoom(chatRoom);

  // Update a chat room
  chatRoom.setDescription("Updated description");
  restApiClient.updateChatRoom(chatRoom);

  // Delete a chat room
  restApiClient.deleteChatRoom("chatroom1");

  // Add user with role "owner" to a chat room
  restApiClient.addOwner("chatroom1", "username");

  // Add user with role "admin" to a chat room
  restApiClient.addAdmin("chatroom1", "username");

  // Add user with role "member" to a chat room
  restApiClient.addMember("chatroom1", "username");

  // Add user with role "outcast" to a chat room
  restApiClient.addOutcast("chatroom1", "username");

  // Get all participants from a specified chat room
  restApiClient.getChatRoomParticipants("chatroom1");

Session related examples

  // Set Shared secret key
  AuthenticationToken authenticationToken = new AuthenticationToken("FQaCIpmRNBq4CfF8");
  // Set Openfire settings (9090 is the port of Openfire Admin Console)
  RestApiClient restApiClient = new RestApiClient("http://testdomain.com", 9090, authenticationToken);

  // Request all active Sessions
  restApiClient.getSessions();

  // Request all active Sessions from a specific user
  restApiClient.getSessions(String username);

System related examples

  // Set Shared secret key
  AuthenticationToken authenticationToken = new AuthenticationToken("FQaCIpmRNBq4CfF8");
  // Set Openfire settings (9090 is the port of Openfire Admin Console)
  RestApiClient restApiClient = new RestApiClient("http://testdomain.com", 9090, authenticationToken);

  // Retrieve all system properties
  restApiClient.getSystemProperties();

  // Retrieve specific system property e.g. "xmpp.domain"
  restApiClient.getSystemProperty("xmpp.domain");

  // Create a system property
  SystemProperty systemProperty = new SystemProperty("propertyName", "propertyValue");
  restApiClient.createSystemProperty(systemProperty);

  // Update a system property
  SystemProperty systemProperty = new SystemProperty("propertyName", "ChangedPropertyValue");
  restApiClient.updateSystemProperty(systemProperty);

  // Delete a system property
  restApiClient.deleteSystemProperty("propertyName");

Group related examples

  // Set Shared secret key
  AuthenticationToken authenticationToken = new AuthenticationToken("FQaCIpmRNBq4CfF8");
  // Set Openfire settings (9090 is the port of Openfire Admin Console)
  RestApiClient restApiClient = new RestApiClient("http://testdomain.com", 9090, authenticationToken);

  // Retrieve all groups
  restApiClient.getGroups();

  // Retrieve specific group
  restApiClient.getGroup("Moderators");

  // Create a group
  GroupEntity groupEntity = new GroupEntity("Moderators", "Moderator Group");
  restApiClient.createGroup(groupEntity);

  // Update a group
  GroupEntity groupEntity = new GroupEntity("Moderators", "Changed Moderator Group description");
  restApiClient.updateGroup(groupEntity);

  // Delete a group
  restApiClient.deleteGroup("Moderators");

Roster related examples

  // Set Shared secret key
  AuthenticationToken authenticationToken = new AuthenticationToken("FQaCIpmRNBq4CfF8");
  // Set Openfire settings (9090 is the port of Openfire Admin Console)
  RestApiClient restApiClient = new RestApiClient("http://testdomain.com", 9090, authenticationToken);

  // Retrieve user roster
  restApiClient.getRoster("testUsername");

  // Create a user roster entry (Possible values for subscriptionType are: -1 (remove), 0 (none), 1 (to), 2 (from), 3 (both))
  RosterItemEntity rosterItemEntity = new RosterItemEntity("testUser2@testdomain.com", "TestUser2", 3);
  // Groups are optional
  List<String> groups = new ArrayList<String>();
  groups.add("Supporter");
  rosterItemEntity.setGroups(groups);
  restApiClient.addRosterEntry("testUsername", rosterItemEntity);

  // Update a user roster entry
  RosterItemEntity rosterItemEntity = new RosterItemEntity("testUser2@testdomain.com", "SomeUser", 3);
  restApiClient.updateRosterEntry("testUsername", rosterItemEntity);

  // Delete a user roster entry
  restApiClient.deleteRosterEntry("testUsername", "testUser2@testdomain.com");

Copyright and license

Created and copyright (c) 2020 by Roman Soldatow (openfire@rmsol.de). REST API Client may be freely distributed under the Apache 2.0 license.