eXo Collaboration implements and provides many public REST APIS to help built-in applications, such as Calendar, Chat and Mail to communicate and transfer data with the server. By using these public REST APIs, extended or 3rd party applications can make use of this to develop cool web applications faster without much implementation.

h1. Calendar application {anchor:id=CSref.PublicRESTAPIs.CalendarApplication}
The Calendar application of eXo Collaboration uses CalendarWebservice to provide all APIs for working with calendars, such as creating personal/group calendars, sharing calendars, managing events/tasks.

The REST API of Calendar portlet is exposed by _org.exoplatform.services.cs.calendar.CalendarWebservice_ class.

|| Service name || Service URL || Location || Description ||
| *CalendarWebservice* | {{$portalname/$restcontextname/cs/calendar}} | - Maven groupId: org.exoplatform.cs {example}{example} - ArtifactId: exo.cs.web.webservice | Call extended services of the Calendar application. |

Details:

* $portalname: The name of the portal
* $restcontextname: The context name of rest webapplication which is deployed to the "$portalname" portal.



* *APIs usage*:

Use the following APIs to build all functions of the Calendar application:

|| Name || Service URL endpoint || Parameters || Expected Values || Description ||
| *checkpermission* | {{{/cs/calendar/checkPermission/{username}/{calendarId}/type}}}} | username {example}{example} calendarId {example}{example} type | user id {example}{example} calendar id {example}{example} {{{ INVALID_TYPE = -1 / PRIVATE_TYPE = 0 / SHARED_TYPE = 1 / PUBLIC_TYPE = 2 }}}|Check the permission of a user to a calendar, aiming at defining if the user has the edit permission to the calendar or not. |
| *event* | {{{/cs/calendar/event/{username}/{eventFeedName}}}} |username {example}{example} eventFeedName | user id {example}{example} string |Return a feed RSS that lists links to access a specific event.|
| *feed* | {{{/cs/calendar/feed/{username}/{feedname}/{filename}}}} | username {example}{example} feedname {example}{example}filename | username {example}{example} string {example}{example} string |Show the content of a feed that is a list of events in the "filename" file. |
| *publicProcess* | {{{/cs/calendar/subscribe/{username}/{calendarId}/{type}}}} | username {example}{example} calendarId {example}{example} type| user id {example}{example} calendar id {example}{example} {{{INVALID_TYPE = -1 / PRIVATE_TYPE = 0 / SHARED_TYPE = 1 / PUBLIC_TYPE = 2}}}  |Process the public calendar when having a remote access request.|
| *privateProcess* | {{{cs/calendar/private/{username}/{calendarId}/{type}}}} | username {example}{example} calendarID {example}{example} type |user id {example}{example} calendar id {example}{example} {{{INVALID_TYPE = -1 / PRIVATE_TYPE = 0 / SHARED_TYPE = 1 / PUBLIC_TYPE = 2}}}|Process the public calendar when having a remote access request. User must enter username and password to access.|
| *getEvents* | {{{/cs/calendar/events/personal/{type}/{calids}/{from}/{to}/{limit}}}}|type {example}{example}calids {example}{example}from {example}{example}to {example}{example}limit|Event/Task {example}{example} Personal calendar id {example}{example}long{example}{example}long{example}{example}integer |Get personal events/tasks of a particular calendar by time range and limit the number of returned events/tasks by the '{{limit}}' parameter. |
| *upcomingEvent* | {{{/cs/calendar/getissues/{currentdatetime}/{type}/{limit}}}} | currentdatatime {example}{example} type {example}{example} limit | valid time format {example}{example} {{{INVALID_TYPE = -1 / PRIVATE_TYPE = 0 / SHARED_TYPE = 1 / PUBLIC_TYPE = 2}}} {example}{example} integer |The list of upcoming events in a specific calendar.|
| *updateStatus* | {{{/cs/calendar/updatestatus/{taskid}}}} | taskid | task id |Update the status of a task. |
| *getCalendars* | /cs/calendar/getcalendars| {{no param}} | {{}} |Get a list of calendars. |

h1. Mail application {anchor:id=CSref.PublicRESTAPIs.MailApplication}

The Mail application of eXo Collaboration uses MailWebservice to provide all APIs for working with mail, such as sending/checking/storing mail to JCR.

REST API of the Mail portlet is exposed by _org.exoplatform.services.cs.mail.MailWebservice_ class.

{docbook}
<warning><para>
The Mail portlet and its services are deprecated. It remains fully supported for eXo customers, however it will not receive any enhancement and will be removed from the product scope in the future.
</para></warning>
{docbook}

|| Service name || Service URL || Location || Description ||
|*MailWebservice* | {{$portalname/$restcontextname/private/cs/mail}} | - Maven groupId: org.exoplatform.cs {example}{example} - artifactId: exo.cs.web.webservice |This service is used to call extended services of the Mail application. |

* *APIs Usage*:
Use the following APIs to build all functions of the Mail application:


|| Name || Service URL endpoint || Parameters || Expected Values || Description ||
|*checkMail* | {{{/checkmail/{username}/{accountId}/{folderId/}}}}/ | username {example}{example} accountID {example}{example} folderId| user id {example}{example} account id {example}{example} folder id |Check mails when having a request.|
|*synchFolders* | {{{/synchfolders/{username}/{accountId}/}}} | username {example}{example} accountID | user id {example}{example} account id |Synchronize the mail folders in the clients and those in the mail server. |
|*stopCheckMail* | {{{/stopcheckmail/{username}/{accountId}/}}}| username {example}{example} accountId| user id {example}{example} account id | Stop checking the mail. |
|*getCheckMailJobInfo* | {{{/checkmailjobinfo/{username}/{accountId}/}}} | username {example}{example} accountId | user id {example}{example} account id| The method to get information of the mail-checking job.|
|*searchemail* | {{{/searchemail/{keywords}}}} | keywords| string |Search information from emails. |


h1. Chat application {anchor:id=CSref.PublicREST_APIs.ChatApplication}

The Chat application uses some APIs to help users create a room, join a room, invite other users to room, or send files, and more.

The Chat application of eXo Collaboration uses two services: RESTXMPPService and FileExchangeService to do these tasks.

{docbook}
<warning><para>
The Chat portlet and its services are deprecated. It remains fully supported for eXo customers, however it will not receive any enhancement and will be removed from the product scope in the future.
</para></warning>
{docbook}

h2. RESTXMPPService {anchor:id=CSref.PublicREST_APIs.RESTXMPPService}

REST API _RESTXMPPService_ of the Chat portlet is exposed by _org.exoplatform.services.xmpp.rest.RESTXMPPService_ class.

|| Service name || Service URL || Location || Description ||
|*RESTXMPPService* | {{$portalname/$restcontextname/xmpp}} | * Maven groupid: org.exoplatform.cs {example}{example} * exo.cs.eXoApplication.chat.service| Implement all actions sent to the Chat server; |


* *APIs Usage*:
Use the following APIs to build all functions of the Chat application:

|| Name || Service URL endpoint || Parameters || Expected Values || Description ||
|*loadJsResourceBundle* | {{{/loadJsResourceBundle/{locale}/}}} | locale| locale id |Read the language files in the Chat server. |
|*createRoom* | {{{/muc/createroom/{username}/}}} | username {example}{example} room {example}{example} nickname| user id {example}{example} room name {example}{example} display name |Create a chat room or a group chat. |
|*configRoom* | {{{/muc/configroom/{username}/}}} | username {example}{example} room | user id {example}{example} room name |Establish the configuration of a chat room. |
|*getRoomConfigForm* | {{{/muc/getroomconfig/{username}/}}} | username {example}{example} room| user id {example}{example} room name |Get the configuration of a chat room created. |
|*getRoomInfo* | {{{/muc/getroominfo/{username}/}}} |username  {example}{example} room| user id {example}{example} string |Get the inforamtion of a chat room created. |
|*getJoinedRooms* | {{{/muc/joinedrooms/{username}/}}} | username| user id|List chat rooms that a user has been joined. |
|*getRooms* | {{{/muc/rooms/{username}/}}}| username| user id |Get a list of group chat or chat rooms created.|
|*declineToRoom* | {{{/muc/decline/{username}/{inviter}/}}} |username {example}{example} inviter {example}{example} room {example}{example} reason | user id {example}{example} user id {example}{example} room name {example}{example} string |Refuse the invitation to join the chat room. |
|*destroyRoom* | {{{/muc/destroy/{username}}}}| username {example}{example} room {example}{example} reason {example}{example} altroom | user id {example}{example} room name {example}{example} string {example}{example} room id |Delete a chat room created. |
|*inviteToRoom* | {{{/muc/invite/{username}/{invitee}/}}}| username {example}{example} invitee {example}{example} room {example}{example} reason| user id {example}{example} user id {example}{example} room name {example}{example} {{{string}}} |Invite other users to join a chat room. |
|*joinRoom* | {{{/muc/join/{username}/}}} |username {example}{example} room {example}{example} nickname {example}{example} password | user id {example}{example} room name {example}{example} display name {example}{example} room password |Join a chat room. |
|*leftRoom* | {{{/muc/leaveroom/{username}/}}} | username {example}{example}  room| user id {example}{example} room name |Leave a chat room. |
|*changeNickname* | {{{/muc/changenickname/{username}/{nickname}/}}} |username {example}{example} nickname| user id {example}{example} display name |Change the nickname of users. |
|*changeAvailabilityStatusInRoom* | {{{/muc/changestatus/{username}/{mode}/}}} | username {example}{example} mood {example}{example} room {example}{example} status| user id {example}{example} presence type {example}{example} room name {example}{example} presence type |Change the status of a user in the chat room. |
|*changeSubject* | {{{muc/changesubject/{username}/}}} |username {example}{example} room {example}{example} subject| user id {example}{example} room name {example}{example} string |Change the subject of a chat room. |
|*manageRoleRoom* | {{{/muc/managerole/{username}/}}} |username {example}{example} room {example}{example} nickname {example}{example} role {example}{example} command| user id {example}{example}room name {example}{example} display name {example}{example} Participant / moderator {example}{example} grant/revoke |Change the role of each user in a chat room. |
|*manageAffilationRoom* | {{{/muc/manageaffiliation/{username}/}}} | username {example}{example} room {example}{example} nickname {example}{example} affiliation {example}{example} command| user id {example}{example} room name {example}{example} display name {example}{example}String affiliation {example}{example}grant / revoke |Change the ownership of a chat room. |
|*kickUserFromRoom* | {{{/muc/kick/{username}/}}} | username {example}{example} nickname {example}{example}room {example}{example}reason | user id {example}{example} display name {example}{example} room name {example}{example} string |Remove a user from the chat room. |
|*banUserFromRoom* | {{{/muc/ban/{username}/}}} |username {example}{example} room {example}{example} name {example}{example} reason| user id {example}{example} room name {example}{example}user id {example}{example} string |Ban a user in the chat room. |
|*addBoddyToRoster* | {{{/roster/add/{username}/{adduser}}}} | username {example}{example} adduser {example}{example} nickname {example}{example} group  | user id {example}{example} use id {example}{example} display name {example}{example} group id|Add a user into the contact list. |
|*updateBoddy* | {{{/roster/update/{username}/{upduser}/}}} |username {example}{example} upduser {example}{example} nickname {example}{example} group | user id {example}{example} user id {example}{example} display name {example}{example} group id|Update new users into the contact list. |
|*createGroup* | {{{/roster/group/{username}/{group}/}}} |username {example}{example} group |user id {example}{example} group id  |Create a chat room. |
|*askForSubscription* | {{{/askforsubscription/{username}/{askuser}/}}} |username {example}{example} askuser {example}{example} nickname | user id {example}{example} user id {example}{example} display name  |Change the presence type of a user into Subscription. |
|*cleanBuddylist* | {{{/rosterclean/{username}/}}} | username | user id |Remove a user from the contact list. |
|*getAllHistory* | {{{/history/getmessages/{usernameto}/{isGroupChat}/}}} |usernameto {example}{example} isGroupChat {example}{example} usernamefrom  | user id {example}{example} true / false {example}{example} user id|Get all the chat history of two users. |
|*getHistoryBetweenDate* | {{{/history/getmessages/{usernameto}/{isGroupChat}/{from}/{to}/}}} |usernameto {example}{example} isgroupchat {example}{example} from {example}{example} to {example}{example} usernamefrom | user id {example}{example} true / false {example}{example} valid date format {example}{example} valid date format  {example}{example} user id|Get the chat history of two users in a specific period. |
|*getHistoryFromDateToNow* | {{{/history/getmessages/{usernameto}/{isGroupChat}/{from}/}}} | username {example}{example} isGroupChat {example}{example} from {example}{example} usernamefrom| user id {example}{example} true / false {example}{example} valid date format {example}{example} valid date format {example}{example} user id  |Get the chat history of two users from a specific date to the current time. |
|*getAllHistoryFile* | {{{/history/file/getmessages/{usernameto}/{isGroupChat}/{clientTimezoneOffset}/}}} |uernameto {example}{example} isGroupChat {example}{example} clientTimezoneOffset {example}{example} usernamefrom | user id {example}{example} true / false {example}{example}  Long {example}{example} user id |Download all the chat history file of two users.|
|*getHistoryFromDateToNowFile* | {{{/history/file/getmessages/{usernameto}/{isGroupChat}/{from}/{clientTimezoneOffset}/}}} |usernameto {example}{example} isGroupChat {example}{example} from {example}{example} clientTimezoneOffset {example}{example} usernamefrom| user id {example}{example} true / false {example}{example} valid date format {example}{example} Long {example}{example} user id |Download the chat history file of two users from a specific date to the current time |
|*getHistoryBetweenDateFile* | {{{/history/file/getmessages/{usernameto}/{isGroupChat}/{from}/{to}/{clientTimezoneOffset}/}}} |usernameto {example}{example} isGroupChat {example}{example} from {example}{example} to {example}{example} clientTimezoneOffset {example}{example} usernamefrom | user id {example}{example} true / false {example}{example}  valid date format {example}{example} valid date format  {example}{example} Long {example}{example} user id|Download the chat history file of two users in the specific date. |
|*getUserInfo* | {{{/getuserinfo/{username}/{needinfo}/}}} | username {example}{example} needinfo| user id {example}{example} string |Get the information of a user. |
|*login2* | {{{/login2/{forcache}/}}}| forcache | |Allow a user to log in the chat server. |
|*logout* | {{{/logout/{username}/{presencestatus}/}}}| username {example}{example} presencestatus |user id {example}{example} presencestatus |Allow a user to log out the chat server. |
|*messageReceive* | {{{/history/messagereceive/{username}/{messageid}/}}} |username{example}{example} messageid | user id {example}{example} message id |Receive a message from other users. |
|*removeBuddy* | {{{/roster/del/{username}/{removeboddy}/}}} |username {example}{example} removeboddy | user id {example}{example} user id |Delete a contact from the contact list.|
|*removeTransport* | {{{/removetransport/{username}/{transport}/}}} |username {example}{example} transport |user id {example}{example} transport servive (e.g: Yahoo, XMPP) |Reset the presence type at the service that is being used. |
|*searchUsers* | {{{/searchuser/{username}/}}} | username {example}{example} search {example}{example} byUsername {example}{example} byName {example}{example} byEmail {example}{example} searchService | user id {example}{example} string {example}{example} true / false {example}{example} true /false {example}{example} true / false {example}{example} string |Search users in the chat server.|
|*sendMessage* | {{{/sendmessage/{username}/}}} | username {example}{example} messageBean| usesr id {example}{example} object |Send an message to other users. |
|*sendMUCMessage* | {{{/muc/sendmessage/{username}/}}} | username {example}{example} messageBean |user id {example}{example} object|Send a message to multile users or a group. |
|*setUserStatus* | {{{/sendstatus/{username}/{status}/}}} | username {example}{example} status | user id {example}{example} available/ unavailabe / do not disturb / away / extend away |Change the status of a user.|
|*subscribeUser* |{{{/subscribeuser/{username}/{subsuser}/}}} | username {example}{example} subsuser| user id {example}{example} user id | Change presence type into Subcribed type. |
|*unsubscribeUser* | {{{/unsubscribeuser/{username}/{unsubsuser}/}}} |username {example}{example} unsubsuser| user id {example}{example} user id |Change presence type into the Unsubscribed type. |
|*acceptFile* | {{{/fileexchange/accept/{username}/{uuid}/}}}| username {example}{example} uuid | user id {example}{example} string |Accept getting a file sent from another user. |
|*rejectFile* | {{{/fileexchange/reject/{username}/{uuid}/}}} | username {example}{example} uuid | user id {example}{example} string|Refuse getting a file sent from another user.|
|*getPreviousStatus* | {{{/getprevstatus/{username}/}}} | username | user id |Get the tatus of a user in the last log-in.|


h2. FileExchangeService {anchor:id=CSref.PublicREST_APIs.FileExchangeService}

REST API _FileExchangeService_ for uploading files is defined in _org.exoplatform.services.xmpp.rest.FileExchangeService_ class.

|| Service name || Service URL || Location || Description ||
|*FileExchangeService* | {{$portalname/$restcontextname/fileexchange}} | - Maven groupid: org.exoplatform.cs {example}{example} - InterfactId: exo.cs.eXoApplication.chat.service| Upload a file to the server and inform the user that the file can be downloaded to the local computer. |

* APIs usage: Use the following APIs to upload and send files to other users:

|| Name ||Service URL endpoint || Parameters || Expected Values ||Description ||
|*upload* | $portalname/$restcontextname/fileexchange | description {example}{example} username {example}{example} requestor {example}{example} isroom| string {example}{example} user id {example}{example} user id {example}{example} true / false |Upload a file to the server.|
