Difference between revisions of "Administration API - Using the API"

[unchecked revision][unchecked revision]
Line 5: Line 5:
  
 
[[File:MailStoreApiTesterScreenshot.png|200px|right|MailStore API Tester]]
 
[[File:MailStoreApiTesterScreenshot.png|200px|right|MailStore API Tester]]
== MailStore API Test Application ==
+
= MailStore API Test Application =
  
 
To help you better understand the samples on this page, we provide a small tool that is able to send commands to the API HTTPS server and display its responses. Simply download the ZIP file provided below and run the included <code>MailStoreApiTester.exe</code>.
 
To help you better understand the samples on this page, we provide a small tool that is able to send commands to the API HTTPS server and display its responses. Simply download the ZIP file provided below and run the included <code>MailStoreApiTester.exe</code>.
Line 15: Line 15:
 
<br style="clear: both;"/>
 
<br style="clear: both;"/>
  
== General Information About Using the Administration API ==
+
= General Information About Using the Administration API =
  
 
The Administration API accepts commands under the following URLs:  
 
The Administration API accepts commands under the following URLs:  
Line 33: Line 33:
 
If the request cannot be processed, the server responds with HTTP error code 500, and the error message is returned as text/plain (not JSON or XML). An exception are asynchronous commands which use a special URL for status queries (as described below).
 
If the request cannot be processed, the server responds with HTTP error code 500, and the error message is returned as text/plain (not JSON or XML). An exception are asynchronous commands which use a special URL for status queries (as described below).
  
=== Example ===
+
== Example ==
  
 
The following is an example for retrieving the information of the user ''johndoe''.
 
The following is an example for retrieving the information of the user ''johndoe''.
  
==== HTTP Request ====
+
=== HTTP Request ===
  
 
  POST /JSON/Invoke/GetUserInfo HTTP/1.1
 
  POST /JSON/Invoke/GetUserInfo HTTP/1.1
Line 44: Line 44:
 
  userName=johndoe
 
  userName=johndoe
  
==== HTTP Response  ====
+
=== HTTP Response  ===
  
 
  HTTP/1.1 200 OK
 
  HTTP/1.1 200 OK
Line 61: Line 61:
 
  }
 
  }
  
== Asynchronously Executed Commands  ==
+
= Asynchronously Executed Commands  =
  
 
Administration API commands, whose execution typically take more time, are executed asynchronously. The server does not return the actual return value but a URL under which the current status (e.g. the return value for fully executed requests) can be requested.  
 
Administration API commands, whose execution typically take more time, are executed asynchronously. The server does not return the actual return value but a URL under which the current status (e.g. the return value for fully executed requests) can be requested.  
Line 67: Line 67:
 
One example for an asynchronously executed API method is ''RebuildStoreIndex''.  
 
One example for an asynchronously executed API method is ''RebuildStoreIndex''.  
  
=== Sample Return Value  ===
+
== Sample Return Value  ==
  
 
  {
 
  {
Line 76: Line 76:
 
If a JSON object is returned which contains a ''statusUrl'' value, this URL can be used to ask for the current status.  
 
If a JSON object is returned which contains a ''statusUrl'' value, this URL can be used to ask for the current status.  
  
=== Structure of the Status Object  ===
+
== Structure of the Status Object  ==
  
 
  {
 
  {
Line 93: Line 93:
  
 
[[de:MailStore_Server_Administration_API]]
 
[[de:MailStore_Server_Administration_API]]
 +
[[en:MailStore_Server_Administration_API]]

Revision as of 22:45, 13 February 2014

In this chapter you can find a description of the MailStore Server Administration API. With the Administration API administrative tasks, such as managing users or storage locations, can be remote controlled from a central location. Communication with the Administration API is done using web requests through HTTPS.

For security reasons, the MailStore Server Administration API is deactivated by default and has to be activated using the MailStore Server Service Configuration.

MailStore API Tester

MailStore API Test Application

To help you better understand the samples on this page, we provide a small tool that is able to send commands to the API HTTPS server and display its responses. Simply download the ZIP file provided below and run the included MailStoreApiTester.exe.

The download comes with the entire C# source code of the test application.

Download MailStoreApiTester.zip


General Information About Using the Administration API

The Administration API accepts commands under the following URLs:

/JSON/Invoke/MethodName

and

/XML/Invoke/MethodName

The first part of the path indicates the return format expected by the client (JSON or XML). JSON is the native return format of the MailStore Server Administration API and is therefore recommended. If XML is requested, an internal automatic conversion to XML is made.

Commands must be sent to the Administration API using the HTTP POST method. The parameters should be transferred in the HTTP body and encoding must always be done using UTF-8. The return value is always UTF-8 encoded respectively.

Please note: A list of all available Administration API commands is available in chapter MailStore Server Administration API Commands.

If the request cannot be processed, the server responds with HTTP error code 500, and the error message is returned as text/plain (not JSON or XML). An exception are asynchronous commands which use a special URL for status queries (as described below).

Example

The following is an example for retrieving the information of the user johndoe.

HTTP Request

POST /JSON/Invoke/GetUserInfo HTTP/1.1
...

userName=johndoe

HTTP Response

HTTP/1.1 200 OK
Content-Type: application/json
...

{
   "userName": "johndoe",
   "fullName": "John Doe",
   "authentication": "integrated",
   "emailAddresses": [
       "johndoe@example.com",
       "doe@example.com"
       ],
   "privileges": "admin"
}

Asynchronously Executed Commands

Administration API commands, whose execution typically take more time, are executed asynchronously. The server does not return the actual return value but a URL under which the current status (e.g. the return value for fully executed requests) can be requested.

One example for an asynchronously executed API method is RebuildStoreIndex.

Sample Return Value

{
   "statusToken": "C467B22E-7057-43BA-B79B-C6140ED514BD",
   "statusUrl": "/JSON/Status/C467B22E-7057-43BA-B79B-C6140ED514BD"
}

If a JSON object is returned which contains a statusUrl value, this URL can be used to ask for the current status.

Structure of the Status Object

{
   "status": "running | succeeded | failed",
   "result": { JSON Object },
   "progressPercentage": 0..100,
   "messages": [
       {
           "type": "line | information | warning | error | unknown",
           "text": "..."
       }
   ]
}

If the returned status is succeeded or failed, each additional status query under the same URL will fail, because once the status is delivered, all internally stored status information is deleted.