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

[unchecked revision][unchecked revision]
Line 4: Line 4:
 
For security reasons, the MailStore Server Administration API is deactivated by default and has to be activated using the [[MailStore Server Service Configuration]].  
 
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 Test Application =
+
== MailStore API Test Application ==
 
[[File:MailStoreApiTesterScreenshot.png|200px|right|MailStore API Tester]]
 
[[File:MailStoreApiTesterScreenshot.png|200px|right|MailStore API Tester]]
  
Line 15: Line 15:
 
<br style="clear: both;"/>
 
<br style="clear: both;"/>
  
= General Information About Using the Administration API =
+
== Executing Regular API Functions ==
  
The Administration API accepts commands under the following URLs:  
+
To execute regular Management API functions, send a HTTP POST request to the following URL:
  
/JSON/Invoke/'''MethodName'''
+
<tt><nowiki>https://<mailstore-server>:8463/api/invoke/<function></nowiki></tt>
  
and  
+
With every request to the API, the username and password of a MailStore Administrator must be submitted following the [[wikipedia:Basic_access_authentication|HTTP Basic Authentication]] specification as described in RFC 2617
  
/XML/Invoke/'''MethodName'''
+
=== Example ===
  
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.  
+
==== HTTP Request ====
 +
<source lang="xml" toolbar="false" gutter="false">
 +
POST /api/invoke/GetEnvironmentInfo HTTP/1.1
 +
User-Agent: curl/7.22.0 (x86_64-pc-linux-gnu) libcurl/7.22.0 OpenSSL/1.0.1 zlib/1.2.3.4 libidn/1.23 librtmp/2.3
 +
Host: dweuthen.mscloud.test:8470
 +
Accept: */*
 +
Cookie: MSWEB_MGM_AUTH=TUidNy4lYFU03ekOUju7udiC1AfxYRCmX%2bb
 +
X-AntiXsrfToken: Lj9SUpcVnVv5t938IgJNgFiAZsLxYRCmX+bQCGFkbWlu
 +
Content-Length: 0
 +
Content-Type: application/x-www-form-urlencoded
 +
</source>
  
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.
+
==== HTTP Response ====
 +
<source lang="xml" toolbar="false" gutter="false">
 +
HTTP/1.1 200 OK
 +
Cache-Control: no-cache,private,no-store,must-revalidate,max-stale=0,post-check=0,pre-check=0
 +
Pragma: no-cache
 +
Content-Length: 770
 +
Content-Type: application/json
 +
Expires: Wed, 22 Jan 2014 15:05:19 GMT
 +
Server: Microsoft-HTTPAPI/2.0
 +
Set-Cookie: MSWEB_MGM_AUTH=Ecru%2fvKOOd1TdbClcEdWAigiRu%2fCJA5dZObQCGFkbWlu;path=/;secure;HttpOnly
 +
Date: Thu, 23 Jan 2014 15:05:19 GMT
  
<p class="msnote">'''Please note:''' A list of all available Administration API commands is available in chapter [[MailStore Server Administration API Commands]].</p>
+
{
 +
  "error": null,
 +
  "token": null,
 +
  "antiXsrfToken": "RPDV65bC7Jap57JwtjvhOBlPBEDCJA5dZObQCGFkbWlu",
 +
  "statusVersion": 2,
 +
  "statusCode": "succeeded",
 +
  "percentProgress": null,
 +
  "statusText": null,
 +
  "result": {
 +
    "version": "8.5.0.9272",
 +
    "copyright": "Copyright (c) 2005-2013 MailStore Software GmbH",
 +
    "licenseeName": "MailStore Software GmbH",
 +
    "licenseeID": 10510,
 +
    "serverName": "server.ms-spe.test",
 +
    "userName": "admin",
 +
    "systemProperties": {
 +
      "processors": [
 +
        "Intel(R) Xeon(R) CPU E5645 @ 2.40GHz",
 +
        "Intel(R) Xeon(R) CPU E5645 @ 2.40GHz"
 +
      ],
 +
      "totalPhysicalMemory": 4398800896,
 +
      "operatingSystem": "Microsoft Windows Server 2012 Standard"
 +
    }
 +
  },
 +
  "logOutput": null
 +
}
 +
</source>
  
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).
+
== Long Running Processes ==
  
== Example ==
+
Some API functions start a long running process that may take several minutes or even hours to complete. To keep track of the progress a unique token is returned upon initial request, which can be used to periodically poll for status updates.
  
The following is an example for retrieving the information of the user ''johndoe''.
+
The overall process is as follows:
  
=== HTTP Request ===
+
# Send HTTP POST to <tt><nowiki>https://<mailstore-server>:8463/api/invoke/VerifyStore</nowiki></tt> in order to execute the function.<br/>
 +
# Check the server's response for the keys <tt>token</tt>, <tt>statusCode</tt> and <tt>statusVersion</tt>.<br/>
 +
# To retrieve status updates, send periodic requests to <tt><nowiki>https://<mailstore-server>:8463/api/get-status</nowiki></tt> with the following parameters:<br/>
 +
{| class="wikitable" style="margin-left:35px"
 +
! Name
 +
! Description
 +
|-
 +
| <tt>token</tt>
 +
| The received unique token for the process.
 +
|-
 +
| <tt>lastKnownStatusVersion</tt>
 +
| Value of <tt>statusVersion</tt> from last response.
 +
|-
 +
| <tt>millisecondsTimeout</tt>
 +
| Time in milliseconds until the the server stops waiting for a new status update to send. If a new status update is available it will be sent to the client immediately, otherwise the last status is repeated.
 +
|}
 +
: 4. The process finished when the <tt>statusCode</tt> is not ''running''.
  
POST /JSON/Invoke/GetUserInfo HTTP/1.1
+
=== Example ===
...
+
 
 +
==== Initial HTTP Request ====
 +
<source lang="xml" toolbar="false" gutter="false">
 +
POST /api/invoke/VerifyStore HTTP/1.1
 +
User-Agent: curl/7.22.0 (x86_64-pc-linux-gnu) libcurl/7.22.0 OpenSSL/1.0.1 zlib/1.2.3.4 libidn/1.23 librtmp/2.3
 +
Host: server.ms-spe.tesst:8470
 +
Accept: */*
 +
Cookie: MSWEB_MGM_AUTH=ZsByPD0aV4gYcGt3DL6elnMSKAaQTyRe%2fqHQCGFkbWlu
 +
X-AntiXsrfToken: BTp4ZWF5n8sDDpI0LG5z5bKYIzakLfzubebQCGFkbWlu
 +
Content-Length: 28
 +
Content-Type: application/x-www-form-urlencoded
 +
 
 +
instanceID=i20140122-01&id=2
 +
</source>
 +
 
 +
==== Initial HTTP Response ====
 +
<source lang="xml" toolbar="false" gutter="false">
 +
HTTP/1.1 200 OK
 +
Cache-Control: no-cache,private,no-store,must-revalidate,max-stale=0,post-check=0,pre-check=0
 +
Pragma: no-cache
 +
Content-Length: 359
 +
Content-Type: application/json
 +
Expires: Wed, 22 Jan 2014 16:13:50 GMT
 +
Server: Microsoft-HTTPAPI/2.0
 +
Set-Cookie: MSWEB_MGM_AUTH=wG332pdxKrKEbmAvsc81kOja7QOG7wDvbebQCGFkbWlu;path=/;secure;HttpOnly
 +
Date: Thu, 23 Jan 2014 16:13:49 GMT
 
   
 
   
userName=johndoe
+
{
 +
  "error": null,
 +
  "token": "sa71c6ef0d880a14eb2220fa87f276710e",
 +
  "antiXsrfToken": "Z1aU+nQNasuCl9pvKGTANHKfFuyG7wDvbebQCGFkbWlu",
 +
  "statusVersion": 3,
 +
  "statusCode": "running",
 +
  "percentProgress": 0,
 +
  "statusText": null,
 +
  "result": null,
 +
  "logOutput": "Verifying file group #2...\r\nCreating a list of messages to be verified...\r\n"
 +
}
 +
</source>
  
=== HTTP Response ===
+
==== Periodic HTTP Request of Progress ====
 +
<source lang="xml" toolbar="false" gutter="false">
 +
POST /api/get-status HTTP/1.1
 +
User-Agent: curl/7.22.0 (x86_64-pc-linux-gnu) libcurl/7.22.0 OpenSSL/1.0.1 zlib/1.2.3.4 libidn/1.23 librtmp/2.3
 +
Host: server.ms-spe.test:8470
 +
Accept: */*
 +
Cookie: MSWEB_MGM_AUTH=wG332pdxKrKEbmAvsc81kOja7QOG7wDvbebQCGFkbWlu
 +
X-AntiXsrfToken: Z1aU+nQNasuCl9pvKGTANHKfFuyG7wDvbebQCGFkbWlu
 +
Content-Length: 90
 +
Content-Type: application/x-www-form-urlencoded
 +
   
 +
token=sa71c6ef0d880a14eb2220fa87f276710e&lastKnownStatusVersion=3&millisecondsTimeout=5000
 +
</source>
  
HTTP/1.1 200 OK
+
==== HTTP Response to Periodic Progress Requests ====
Content-Type: application/json
+
<source lang="xml" toolbar="false" gutter="false">
...
+
HTTP/1.1 200 OK
 +
Cache-Control: no-cache,private,no-store,must-revalidate,max-stale=0,post-check=0,pre-check=0
 +
Pragma: no-cache
 +
Content-Length: 309
 +
Content-Type: application/json
 +
Expires: Wed, 22 Jan 2014 16:21:55 GMT
 +
Server: Microsoft-HTTPAPI/2.0
 +
Set-Cookie: MSWEB_MGM_AUTH=Fo00yVkaGWgRFyhpf4KPDdDMdLrxM4AQb%2bbQCGFkbWlu;path=/;secure;HttpOnly
 +
Date: Thu, 23 Jan 2014 16:21:55 GMT
 
   
 
   
{
+
{
    "userName": "johndoe",
+
  "error": null,
    "fullName": "John Doe",
+
  "token": null,
    "authentication": "integrated",
+
  "antiXsrfToken": "Zrt40mK3S5xIG3HOce688LZ/QCXxM4AQb+bQCGFkbWlu",
    "emailAddresses": [
+
  "statusVersion": 4,
        "johndoe@example.com",
+
  "statusCode": "running",
        "doe@example.com"
+
  "percentProgress": 0,
        ],
+
  "statusText": null,
    "privileges": "admin"
+
  "result": null,
}
+
  "logOutput": "500047 messages are about to be verified.\r\nVerifying...\r\n"
 
+
}
= Asynchronously Executed Commands  =
+
</source>
  
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.  
+
==== Final HTTP Response ====
 +
<source lang="xml" toolbar="false" gutter="false">
 +
HTTP/1.1 200 OK
 +
Cache-Control: no-cache,private,no-store,must-revalidate,max-stale=0,postcheck=0,pre-check=0
 +
Pragma: no-cache
 +
Content-Length: 242
 +
Content-Type: application/json
 +
Expires: Tue, 29 Oct 2013 16:09:42 GMT
 +
Server: Microsoft-HTTPAPI/2.0
 +
Set-Cookie: MSWEB_MGM_AUTH=ZsByPD0aV4gYcGt3DL6elnMSKAaQTyRe%2fqHQCGFkbWlu;path=/;secure;HttpOnly
 +
Date: Wed, 30 Oct 2013 16:09:41 GMT
  
One example for an asynchronously executed API method is ''RebuildStoreIndex''.
+
{
 +
  "error": null,
 +
  "token": null,
 +
  "antiXsrfToken": "Dg5geOu431l/5k36IXd13FlqLQ0Ki6ElcObQCGFkbWlu"
 +
  "statusVersion": 269,
 +
  "statusCode": "succeeded",
 +
  "percentProgress": null,
 +
  "statusText": null,
 +
  "result": null,
 +
  "logOutput": null
 +
}
 +
</source>
  
== Sample Return Value  ==
+
== Error Handling ==
 +
Additionally to handling protocol specific issues such as HTTP or TCP errors, developers receive detailed information from the API itself in case the request did not succeed.
  
{
+
In case the request was successfully be processed, the response will contain:
    "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.
+
  "error": null
  
== Structure of the Status Object  ==
+
Otherwise in the event of a failure the error key will have the following structure
  
{
+
  "error": {
    "status": "running | succeeded | failed",
+
     "message": string,
    "result": { JSON Object },
+
     "details": string
     "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.
+
allowing developers to display a meaningful error message and further technical details.
  
 
[[de:MailStore_Server_Administration_API]]
 
[[de:MailStore_Server_Administration_API]]
 
[[en:MailStore_Server_Administration_API]]
 
[[en:MailStore_Server_Administration_API]]

Revision as of 12:47, 22 June 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 Test Application

MailStore API Tester

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


Executing Regular API Functions

To execute regular Management API functions, send a HTTP POST request to the following URL:

https://<mailstore-server>:8463/api/invoke/<function>

With every request to the API, the username and password of a MailStore Administrator must be submitted following the HTTP Basic Authentication specification as described in RFC 2617

Example

HTTP Request

POST /api/invoke/GetEnvironmentInfo HTTP/1.1
User-Agent: curl/7.22.0 (x86_64-pc-linux-gnu) libcurl/7.22.0 OpenSSL/1.0.1 zlib/1.2.3.4 libidn/1.23 librtmp/2.3
Host: dweuthen.mscloud.test:8470
Accept: */*
Cookie: MSWEB_MGM_AUTH=TUidNy4lYFU03ekOUju7udiC1AfxYRCmX%2bb
X-AntiXsrfToken: Lj9SUpcVnVv5t938IgJNgFiAZsLxYRCmX+bQCGFkbWlu
Content-Length: 0
Content-Type: application/x-www-form-urlencoded

HTTP Response

HTTP/1.1 200 OK
Cache-Control: no-cache,private,no-store,must-revalidate,max-stale=0,post-check=0,pre-check=0
Pragma: no-cache
Content-Length: 770
Content-Type: application/json
Expires: Wed, 22 Jan 2014 15:05:19 GMT
Server: Microsoft-HTTPAPI/2.0
Set-Cookie: MSWEB_MGM_AUTH=Ecru%2fvKOOd1TdbClcEdWAigiRu%2fCJA5dZObQCGFkbWlu;path=/;secure;HttpOnly
Date: Thu, 23 Jan 2014 15:05:19 GMT

{
   "error": null,
   "token": null,
   "antiXsrfToken": "RPDV65bC7Jap57JwtjvhOBlPBEDCJA5dZObQCGFkbWlu",
   "statusVersion": 2,
   "statusCode": "succeeded",
   "percentProgress": null,
   "statusText": null,
   "result": {
     "version": "8.5.0.9272",
     "copyright": "Copyright (c) 2005-2013 MailStore Software GmbH",
     "licenseeName": "MailStore Software GmbH",
     "licenseeID": 10510,
     "serverName": "server.ms-spe.test",
     "userName": "admin",
     "systemProperties": {
       "processors": [
         "Intel(R) Xeon(R) CPU E5645 @ 2.40GHz",
         "Intel(R) Xeon(R) CPU E5645 @ 2.40GHz"
       ],
       "totalPhysicalMemory": 4398800896,
       "operatingSystem": "Microsoft Windows Server 2012 Standard"
     }
   },
   "logOutput": null
 }

Long Running Processes

Some API functions start a long running process that may take several minutes or even hours to complete. To keep track of the progress a unique token is returned upon initial request, which can be used to periodically poll for status updates.

The overall process is as follows:

  1. Send HTTP POST to https://<mailstore-server>:8463/api/invoke/VerifyStore in order to execute the function.
  2. Check the server's response for the keys token, statusCode and statusVersion.
  3. To retrieve status updates, send periodic requests to https://<mailstore-server>:8463/api/get-status with the following parameters:
Name Description
token The received unique token for the process.
lastKnownStatusVersion Value of statusVersion from last response.
millisecondsTimeout Time in milliseconds until the the server stops waiting for a new status update to send. If a new status update is available it will be sent to the client immediately, otherwise the last status is repeated.
4. The process finished when the statusCode is not running.

Example

Initial HTTP Request

POST /api/invoke/VerifyStore HTTP/1.1
User-Agent: curl/7.22.0 (x86_64-pc-linux-gnu) libcurl/7.22.0 OpenSSL/1.0.1 zlib/1.2.3.4 libidn/1.23 librtmp/2.3
Host: server.ms-spe.tesst:8470
Accept: */*
Cookie: MSWEB_MGM_AUTH=ZsByPD0aV4gYcGt3DL6elnMSKAaQTyRe%2fqHQCGFkbWlu
X-AntiXsrfToken: BTp4ZWF5n8sDDpI0LG5z5bKYIzakLfzubebQCGFkbWlu
Content-Length: 28
Content-Type: application/x-www-form-urlencoded

instanceID=i20140122-01&id=2

Initial HTTP Response

HTTP/1.1 200 OK
Cache-Control: no-cache,private,no-store,must-revalidate,max-stale=0,post-check=0,pre-check=0
Pragma: no-cache
Content-Length: 359
Content-Type: application/json
Expires: Wed, 22 Jan 2014 16:13:50 GMT
Server: Microsoft-HTTPAPI/2.0
Set-Cookie: MSWEB_MGM_AUTH=wG332pdxKrKEbmAvsc81kOja7QOG7wDvbebQCGFkbWlu;path=/;secure;HttpOnly
Date: Thu, 23 Jan 2014 16:13:49 GMT
 
{
  "error": null,
  "token": "sa71c6ef0d880a14eb2220fa87f276710e",
  "antiXsrfToken": "Z1aU+nQNasuCl9pvKGTANHKfFuyG7wDvbebQCGFkbWlu",
  "statusVersion": 3,
  "statusCode": "running",
  "percentProgress": 0,
  "statusText": null,
  "result": null,
  "logOutput": "Verifying file group #2...\r\nCreating a list of messages to be verified...\r\n"
}

Periodic HTTP Request of Progress

POST /api/get-status HTTP/1.1
User-Agent: curl/7.22.0 (x86_64-pc-linux-gnu) libcurl/7.22.0 OpenSSL/1.0.1 zlib/1.2.3.4 libidn/1.23 librtmp/2.3
Host: server.ms-spe.test:8470
Accept: */*
Cookie: MSWEB_MGM_AUTH=wG332pdxKrKEbmAvsc81kOja7QOG7wDvbebQCGFkbWlu
X-AntiXsrfToken: Z1aU+nQNasuCl9pvKGTANHKfFuyG7wDvbebQCGFkbWlu
Content-Length: 90
Content-Type: application/x-www-form-urlencoded
 
token=sa71c6ef0d880a14eb2220fa87f276710e&lastKnownStatusVersion=3&millisecondsTimeout=5000

HTTP Response to Periodic Progress Requests

HTTP/1.1 200 OK
Cache-Control: no-cache,private,no-store,must-revalidate,max-stale=0,post-check=0,pre-check=0
Pragma: no-cache
Content-Length: 309
Content-Type: application/json
Expires: Wed, 22 Jan 2014 16:21:55 GMT
Server: Microsoft-HTTPAPI/2.0
Set-Cookie: MSWEB_MGM_AUTH=Fo00yVkaGWgRFyhpf4KPDdDMdLrxM4AQb%2bbQCGFkbWlu;path=/;secure;HttpOnly
Date: Thu, 23 Jan 2014 16:21:55 GMT
 
{
  "error": null,
  "token": null,
  "antiXsrfToken": "Zrt40mK3S5xIG3HOce688LZ/QCXxM4AQb+bQCGFkbWlu",
  "statusVersion": 4,
  "statusCode": "running",
  "percentProgress": 0,
  "statusText": null,
  "result": null,
  "logOutput": "500047 messages are about to be verified.\r\nVerifying...\r\n"
}

Final HTTP Response

HTTP/1.1 200 OK
Cache-Control: no-cache,private,no-store,must-revalidate,max-stale=0,postcheck=0,pre-check=0
Pragma: no-cache
Content-Length: 242
Content-Type: application/json
Expires: Tue, 29 Oct 2013 16:09:42 GMT
Server: Microsoft-HTTPAPI/2.0
Set-Cookie: MSWEB_MGM_AUTH=ZsByPD0aV4gYcGt3DL6elnMSKAaQTyRe%2fqHQCGFkbWlu;path=/;secure;HttpOnly
Date: Wed, 30 Oct 2013 16:09:41 GMT

{
  "error": null,
  "token": null,
  "antiXsrfToken": "Dg5geOu431l/5k36IXd13FlqLQ0Ki6ElcObQCGFkbWlu"
  "statusVersion": 269,
  "statusCode": "succeeded",
  "percentProgress": null,
  "statusText": null,
  "result": null,
  "logOutput": null
}

Error Handling

Additionally to handling protocol specific issues such as HTTP or TCP errors, developers receive detailed information from the API itself in case the request did not succeed.

In case the request was successfully be processed, the response will contain:

 "error": null

Otherwise in the event of a failure the error key will have the following structure

 "error": {
   "message": string,
   "details": string
 }

allowing developers to display a meaningful error message and further technical details.