MongooseIM's REST API for frontend or client

In addition to the regular XMPP connection methods such as TCP (with TLS/STARTTLS), WebSockets and BOSH, MongooseIM provides parts of its functionality over a REST API.

Assumptions

  1. Every request has to be authenticated. Please see the Authentication section for more details.
  2. We advise that this API is served over HTTPS.
  3. User registration has to be done via other methods (f.e. using the REST API for backend services).
  4. The relevant endpoint has to be configured on the server side. See the configuration section.
  5. A list of provided actions is documented with Swagger. See the beatiful specification.

Authentication

The only possible authentication method for the time being is Basic Authentication. The userid part is user's bare JID and the password is the same as that used to register the user's account.

Bare JID

To ilustrate what bare JIDs are, let's assume your MongooseIM server's hostname is wonderland.com and the user is alice. In this case the bare JID for her is just: alice@wonderland.com. This value should be used as the userid in the Basic Authentication method for all the REST API calls.

Configuration

In order to enable the REST API, the following configuration should be added to the listen section in mongooseim.cfg file.

  { 8089 , ejabberd_cowboy, [
      {num_acceptors, 10},
      {max_connections, 1024},
      {compress, true},
      {ssl, [{certfile, "priv/ssl/fake_cert.pem"}, {keyfile, "priv/ssl/fake_key.pem"}, {password, ""}]},
      {modules, [
          {"_", "/api/messages/[:with]", mongoose_client_api_messages, []},
          {"_", "/api/rooms/:id/messages",    mongoose_client_api_rooms_messages, []},
          {"_", "/api/rooms/:id/users/[:user]",    mongoose_client_api_rooms_users, []},
          {"_", "/api/rooms/[:id]",    mongoose_client_api_rooms, []}
      ]}
  ]}

The most important part of the above example is the modules lists where the relevant REST API functionalities are enabled and exposed on the given paths. By default the REST API is exposed on port 8089 but this can be changed to whatever is more convenient.

For more details about possible ejabberd_cowboy configuration parameters please see the relevant documentation in the Listener modules.

Smack library support

REST API can fetch messages for Smack Stanza Properties.

For example if we have properties in the stanza like: <message xml:lang='en' to='alice@localhost' id='123' type='chat'> <body xml:lang='en_US'>Hi!</body> <properties xmlns="http://www.jivesoftware.com/xmlns/xmpp/properties" <property> <name>some_number</name> <value type='integer'>123</value> <property> <property> <name>some_string</name> <value type='string'>abc</value> <property> </properties> </message> then in the final json message these properties will be converted to json map without tag names and all types will be taken as string:

    {   "to": "alice@localhost",
        "timestamp": 1531329049949,
        "id": "123",
        "from": "bob@localhost",
        "body": "Hi!",
        "properties":{
            "some_number":"123",
            "some_string":"abc"
        }
    }

OpenAPI specifications

See the beautiful Swagger documentation for more information.

Swagger