Clever Geek Handbook

How to use REST and SOAP API in Zimbra OSE

Like almost any modern web service, Zimbra OSE has data exchange interfaces that allow you to access various server functions and data stored on it. APIs are used to develop various applications and to integrate Zimbra with other corporate systems. Zimbra OSE supports REST API and SOAP API. In this article, we will analyze the differences, scopes and examples of using SOAP and REST API in Zimbra OSE.



image



SOAP and REST API - what are the differences?



While the SOAP API and the REST API actually perform the same function, there are more differences than similarities between them, and those differences begin with the definition. So, if SOAP is a protocol that is designed to standardize the exchange of data between web services, regardless of what language they are written in, then REST is an architectural style of a web service, which implies a number of restrictions in accordance with which a web service is created ...



Specifically, in Zimbra, the REST API and SOAP API differ in scope. The REST API is used here only for CRUD operations, that is, for creating, reading, updating and deleting objects on the server. Therefore, the REST API is mainly used to create simple integrations with third-party systems, since it allows you to download data from Zimbra in various formats, such as xml, json, rss, html, zip, tar, tgz, ics, ifb, csv and others, and also import data into Zimbra. The SOAP API can be used for other operations in addition to managing mailbox data. Another significant difference is that REST is less secure than SOAP.



The API differs from the command line, which in Zimbra OSE has even more functionality and supports the formation of bash scripts, in that they do not require access to the Zimbra system account on the mail server.



REST API The



REST API is represented in Zimbra OSE by a set of methods for working with mail, calendars, tasks and contacts. Among them:



  • Get Folder - export the contents of a mail folder
  • Import Message - import a message into a mail folder
  • Get Contacts - export contacts
  • Import Contacts - import contacts
  • Get Calendar - export calendar
  • Get FreeBusy - Export Free Busy Data
  • Import Appointments - import meeting data
  • Get Tasks - export tasks
  • Get Item - export item


All of the above methods require user authentication. It can be done by adding authentication data to the query string, as well as having received an authentication token, use it to log into the server. You can get a token by entering the authentication data of the server administrator, as well as by entering the authentication data of the user for whom the token is issued: 



curl --user 'admin:p@$$w0rD' -k 'https://example.ru/home/user@example.ru/Inbox/?fmt=sync&auth=sc' -c '~/token.txt'
curl --user 'user:qwerty123' -k 'https://example.ru/home/user@example.ru/Inbox/?fmt=sync&auth=sc' -c '~/token.txt'


The result of this command will be the creation of a token.txt file in the user's home folder that will contain the authentication token. Please note that this token has a limited expiration date and after this period you will need to issue a new token to access the Zimbra mailbox via REST requests. The token itself is a 313-character string starting with '0_'.







Having copied this token, you can use it to access the mailbox data through the REST API. For example, you can get the contents of the Zimbra user's Inbox using a command like curl -k 'https://example.ru/home/user@example.ru/Inbox/?fmt=rss&auth=qp&zauthtoken=0_xxx'> ~ / inbox xmlwhere 0_xxx is the authentication token, auth = qp is the token authentication method, fmt = rss is the output format, and ~ / inbox xml is the file to which the contents of the Inbox will be exported.



By adding various arguments to the REST request, you can partially export data from the Inbox. For example:



  • example.ru : 7070/home/user@example.ru/inbox? fmt = xml & query = agreement - this link in the REST request will allow you to receive in the form of an xml file all user's letters from the Inbox folder containing the word "Agreement"
  • example.ru : 7070/home/user@example.ru/inbox? fmt = xml & query = subject: agreement - allows you to receive in the form of an xml file all user's letters from the Inbox folder, the subject of which contains the word "Agreement"
  • example.ru:7070/home/user@example.ru/inbox?fmt=xml&query=is:unread — xml- «»


In order to export the user's contacts, use the link to his contacts folder curl -k 'https://example.ru:7070/home/user@example.ru/contacts?fmt=csv&auth=qp&zauthtoken=0_xxx'> ~ / contacts .csv CURL is



also used to import contacts. For example, using the command curl -k --upload-file ~ / contacts.csv 'https://example.ru:7070/home/user@example.ru/contacts?fmt=csv&auth=qp&zauthtoken=0_xxx you can import CSV -file with contacts.



The main value of the REST API is that all operations that are carried out using it lend themselves well to automation using ordinary bash scripts. For example, if you get the entire list of users with the command zmprov -l gaa>users.txt, then you can use the resulting file for sequential execution of routine operations. For example, to import contacts to the address book, export emails, and so on. Therefore, the REST API can be used to write the simplest, simplest CRUB applications for data synchronization between various information systems at enterprises. To create programs based on the REST API, we recommend using the free and free SoapUI program , which allows you to visually create SOAP and REST requests and view the responses to them.



SOAP API



The SOAP API is much more complex to work with than the REST API, but it has many more features. In addition to managing data stored on the server, SOAP API allows you to manage accounts, domains, in fact, providing access to all the functionality of Zimbra. This is why the SOAP API is used to write more complex client applications. For example, to change account settings and therefore is used to create more advanced applications. For example, the Zimbra OSE web client communicates with the server using the SOAP API.



As mentioned above, SOAP is a protocol for the exchange of rigidly structured xml messages, in which one application can transmit data to another. The transport for transmitting SOAP messages is usually HTTP.



The SOAP API in Zimbra OSE is broken down into several constituent parts. Among them:



  • zimbraAccount - a set of SOAP methods responsible for interacting with user accounts
  • zimbraAdmin - a set of SOAP methods responsible for performing administrative actions
  • ZimbraMail is a set of SOAP methods responsible for managing data on the server.


To work properly with the SOAP API, you need the WSDL: xml files, which describe the SOAP methods available for Zimbra. You can download them directly from your server using the links:





You will also need xsd files with descriptions for the various sections of the SOAP API. You can also download them from your server using the following links:





After importing WSDL into SoapUI, a toolbar appears in it with methods for Zimbra OSE and you can compose various applications from them. Considering the vast possibilities provided by the SOAP API, it becomes possible to create applications not only to automate tasks for managing user content, but also to automate the editing of various settings, create, delete and change domains, users and service classes.



Most SOAP requests require authentication. There are SOAP Auth methods in zimbraAdmin and zimbraAccount for this. An example SOAP request for authentication would look like this 



<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:zimbra" xmlns:urn1="urn:zimbraAccount">
   <soapenv:Header>
      <urn:context xmlns:urn="urn:zimbra"/>
   </soapenv:Header>
   <soapenv:Body>
      <urn1:AuthRequest xmlns:urn1="urn:zimbraAccount">
         <urn1:account by="name">user@example.ru</urn1:account>
         <urn1:password>qwerty123</urn1:password>
      </urn1:AuthRequest>
   </soapenv:Body>
</soapenv:Envelope>


In this example, user@example.ru is the username and qwerty123 is his password. Also, in the address bar of the request, do not forget to specify https as the connection method, otherwise you may encounter a disconnection from the Zimbra side. The response from the server will look like this: 



<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Header>
      <context xmlns="urn:zimbra">
         <change token="5489"/>
      </context>
   </soap:Header>
   <soap:Body>
      <AuthResponse xmlns="urn:zimbraAccount">
         <authToken>0_xxx</authToken>
         <lifetime>172799986</lifetime>
         <skin>zextras</skin>
      </AuthResponse>
   </soap:Body>
</soap:Envelope>


It contains the authentication token in the field, the expiration date of this token (lifetime) in milliseconds, and the name of the skin used.







For example, let's create a request to send an email to Zimbra OSE. An example of a corresponding SOAP request would look like this: 



<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:zimbra" xmlns:urn1="urn:zimbraMail">
   <soapenv:Header>
      <context xmlns="urn:zimbra">
         <authToken>0_xxx</authToken>
      </context>
   </soapenv:Header>
   <soapenv:Body>
      <SendMsgRequest xmlns="urn:zimbraMail">
         <m su="">
            <content></content>
            <e a="admin@example.ru" t="f" p="admin" />
            <e a="ivanov@example.ru.com" t="t" p="Ivanov" />
         </m>
      </SendMsgRequest>
   </soapenv:Body>
</soapenv:Envelope>


Here, in the authToken field, you must specify the previously received authentication token, in the SendMsgRequest field, specify the subject and text of the letter, as well as the accounts and names of the sender and recipient.



In this case, we have manually compiled several SOAP and REST requests for Zimbra. However, their formation can be automated by creating scripts in various programming languages. About this in one of our next articles.


More articles:


All Articles