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

[unchecked revision][checked revision]
(Created page with "__NOTOC__ Im Folgenden finden Sie eine Beschreibung der MailStore Server Management API. With the Management API administrative tasks, such as managing users or storage locati...")
 
 
(25 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 
__NOTOC__
 
__NOTOC__
Im Folgenden finden Sie eine Beschreibung der MailStore Server Management API. With the Management API administrative tasks, such as managing users or storage locations, can be telecontrolled from a central location. Communication with the Management API is done using web requests through HTTPS.  
+
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 Management 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]]. When you are connecting to the API and using a hostname other than ''localhost'' or ''127.0.0.1'' you have to change the password of the admin user before.
  
== General Information about Using the Management API ==
+
== Executing Regular API Functions ==
  
The Management 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.
 +
When a function needs additional data, this data must be send urlencoded. The HTTP header Content-Type: application/x-www-form-urlencoded should be set.
  
/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 Management API and is therefore recommended. If XML is requested, an internal automatic conversion in XML is made.  
+
==== HTTP Request ====
 +
<source lang="xml" toolbar="false" gutter="false">
 +
POST /api/invoke/GetServerInfo HTTP/1.1
 +
Authorization: Basic YWRtaW46UGFzc3cwcmQ=
 +
User-Agent: curl/7.35.0
 +
Host: mailstore.example.com:8463
 +
Accept: */*
 +
Content-Length: 0
  
Befehle müssen über die HTTP-POST-Methode an die Management API gesendet werden. Die Parameter sind dabei im HTTP-Body zu übertragen und als Zeichencodierung muss immer UTF-8 verwendet werden. Der Rückgabewert ist entsprechend ebenfalls immer UTF-8 kodiert. Eine Übersicht aller zur Verfügung stehenden Management API-Befehle finden Sie unter [[MailStore Server Management API Commands]].
+
</source>
  
Kann die Anfrage nicht erfolgreich bearbeitet werden, antwortet der Server mit dem HTTP-Fehlercode 500, die Rückgabe der Fehlermeldung erfolgt als text/plain (nicht als JSON oder XML). Ausnahme sind asynchrone Kommandos, bei denen eine Statusabfrage über eine spezielle URL erfolgt (siehe unten).  
+
==== 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: 251
 +
Content-Type: application/json
 +
Expires: Wed, 25 Jun 2014 14:13:43 GMT
 +
Server: Microsoft-HTTPAPI/2.0
 +
Date: Thu, 26 Jun 2014 14:13:43 GMT
 +
 +
{
 +
  "error": null,
 +
  "token": null,
 +
  "statusVersion": 2,
 +
  "statusCode": "succeeded",
 +
  "percentProgress": null,
 +
  "statusText": null,
 +
  "result": {
 +
    "version": "9.0.0.9702",
 +
    "machineName": "MAILSTORE"
 +
  },
 +
  "logOutput": null
 +
}
 +
</source>
 +
 
 +
The response includes a UTF-8 BOM.
 +
 
 +
To get a list of all available functions, send a POST request to <nowiki>https://<mailstore-server>:8463/api/get-metadata</nowiki>.
 +
 
 +
== 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.  
  
=== Beispiel  ===
+
The overall process is as follows:
  
Im Folgenden ein Beispiel für das Abrufen der Informationen des Benutzers ''johndoe''.
+
# 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''.
  
==== HTTP-Request ====
+
=== Example ===
  
POST /JSON/Invoke/GetUserInfo HTTP/1.1
+
==== Initial HTTP Request ====
...
+
<source lang="xml" toolbar="false" gutter="false">
 +
POST /api/invoke/VerifyStore HTTP/1.1
 +
Authorization: Basic YWRtaW46UGFzc3cwcmQ=
 +
User-Agent: curl/7.35.0
 +
Host: mailstore.example.com:8463
 +
Accept: */*
 +
Content-Length: 5
 +
Content-Type: application/x-www-form-urlencoded
 
   
 
   
userName=johndoe
+
id=11
 +
</source>
  
==== HTTP-Response ====
+
==== 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: 290
 +
Content-Type: application/json
 +
Expires: Wed, 25 Jun 2014 14:15:41 GMT
 +
Server: Microsoft-HTTPAPI/2.0
 +
Date: Thu, 26 Jun 2014 14:15:41 GMT
 +
 +
{
 +
  "error": null,
 +
  "token": "b3af0ebae4dd755d1a54b9756817baee",
 +
  "statusVersion": 3,
 +
  "statusCode": "running",
 +
  "percentProgress": 0,
 +
  "statusText": null,
 +
  "result": null,
 +
  "logOutput": "Verifying file group #11...\r\nCreating a list of messages to be verified...\r\n"
 +
}
 +
</source>
  
HTTP/1.1 200 OK
+
==== Periodic HTTP Request of Progress ====
Content-Type: application/json
+
<source lang="xml" toolbar="false" gutter="false">
...
+
POST /api/get-status HTTP/1.1
+
Authorization: Basic YWRtaW46UGFzc3cwcmQ=
{
+
User-Agent: curl/7.35.0
    "userName": "johndoe",
+
Host: spe.example.com:8474
    "fullName": "John Doe",
+
Accept: */*
    "authentication": "integrated",
+
Content-Length: 90
    "emailAddresses": [
+
Content-Type: application/x-www-form-urlencoded
        "johndoe@example.com",
+
 
        "doe@example.com"
+
token=b3af0ebae4dd755d1a54b9756817baee&lastKnownStatusVersion=3&millisecondsTimeout=5000
        ],
+
</source>
    "privileges": "admin"
 
}
 
  
== Asynchronously Executed Commands  ==
+
==== HTTP Response to Periodic Progress Requests ====
 +
<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: 242
 +
Content-Type: application/json
 +
Expires: Wed, 25 Jun 2014 14:08:15 GMT
 +
Server: Microsoft-HTTPAPI/2.0
 +
Date: Thu, 26 Jun 2014 14:08:15 GMT
 +
 
 +
{
 +
  "error": null,
 +
  "token": "b3af0ebae4dd755d1a54b9756817baee",
 +
  "statusVersion": 9,
 +
  "statusCode": "running",
 +
  "percentProgress": 0,
 +
  "statusText": null,
 +
  "result": null,
 +
  "logOutput": "  400 messages verified...\r\n"
 +
}
 +
</source>
  
Management 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,post-check=0,pre-check=0
 +
Pragma: no-cache
 +
Content-Length: 242
 +
Content-Type: application/json
 +
Expires: Wed, 25 Jun 2014 15:08:15 GMT
 +
Server: Microsoft-HTTPAPI/2.0
 +
Date: Thu, 26 Jun 2014 15:08:15 GMT
 +
 +
{
 +
  "error": null,
 +
  "token": null,
 +
  "statusVersion": 269,
 +
  "statusCode": "succeeded",
 +
  "percentProgress": null,
 +
  "statusText": null,
 +
  "result": null,
 +
  "logOutput": null
 +
}
 +
</source>
  
One example for an asynchronously executed API method is ''RebuildStoreIndex''.  
+
== 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.
  
=== Sample Return Value  ===
+
In case the request was successfully be processed, the response will contain:
  
{
+
  "error": null
    "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.
+
Otherwise in the event of a failure the error key will have the following structure
  
=== Structure of the Status Object  ===
+
  "error": {
 +
    "message": string,
 +
    "details": string
 +
  }
  
{
+
allowing developers to display a meaningful error message and further technical details.
    "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.
+
[[de:MailStore_Server_Administration_API]]
 +
[[en:MailStore_Server_Administration_API]]

Latest revision as of 15:30, 23 March 2021

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. When you are connecting to the API and using a hostname other than localhost or 127.0.0.1 you have to change the password of the admin user before.

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. When a function needs additional data, this data must be send urlencoded. The HTTP header Content-Type: application/x-www-form-urlencoded should be set.

Example

HTTP Request

POST /api/invoke/GetServerInfo HTTP/1.1
Authorization: Basic YWRtaW46UGFzc3cwcmQ=
User-Agent: curl/7.35.0
Host: mailstore.example.com:8463
Accept: */*
Content-Length: 0

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: 251
Content-Type: application/json
Expires: Wed, 25 Jun 2014 14:13:43 GMT
Server: Microsoft-HTTPAPI/2.0
Date: Thu, 26 Jun 2014 14:13:43 GMT
 
{
  "error": null,
  "token": null,
  "statusVersion": 2,
  "statusCode": "succeeded",
  "percentProgress": null,
  "statusText": null,
  "result": {
    "version": "9.0.0.9702",
    "machineName": "MAILSTORE"
  },
  "logOutput": null
}

The response includes a UTF-8 BOM.

To get a list of all available functions, send a POST request to https://<mailstore-server>:8463/api/get-metadata.

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
Authorization: Basic YWRtaW46UGFzc3cwcmQ=
User-Agent: curl/7.35.0
Host: mailstore.example.com:8463
Accept: */*
Content-Length: 5
Content-Type: application/x-www-form-urlencoded
 
id=11

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: 290
Content-Type: application/json
Expires: Wed, 25 Jun 2014 14:15:41 GMT
Server: Microsoft-HTTPAPI/2.0
Date: Thu, 26 Jun 2014 14:15:41 GMT
 
{
  "error": null,
  "token": "b3af0ebae4dd755d1a54b9756817baee",
  "statusVersion": 3,
  "statusCode": "running",
  "percentProgress": 0,
  "statusText": null,
  "result": null,
  "logOutput": "Verifying file group #11...\r\nCreating a list of messages to be verified...\r\n"
}

Periodic HTTP Request of Progress

POST /api/get-status HTTP/1.1
Authorization: Basic YWRtaW46UGFzc3cwcmQ=
User-Agent: curl/7.35.0
Host: spe.example.com:8474
Accept: */*
Content-Length: 90
Content-Type: application/x-www-form-urlencoded
  
token=b3af0ebae4dd755d1a54b9756817baee&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: 242
Content-Type: application/json
Expires: Wed, 25 Jun 2014 14:08:15 GMT
Server: Microsoft-HTTPAPI/2.0
Date: Thu, 26 Jun 2014 14:08:15 GMT
  
{
  "error": null,
  "token": "b3af0ebae4dd755d1a54b9756817baee",
  "statusVersion": 9,
  "statusCode": "running",
  "percentProgress": 0,
  "statusText": null,
  "result": null,
  "logOutput": "  400 messages verified...\r\n"
}

Final 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: 242
Content-Type: application/json
Expires: Wed, 25 Jun 2014 15:08:15 GMT
Server: Microsoft-HTTPAPI/2.0
Date: Thu, 26 Jun 2014 15:08:15 GMT
 
{
  "error": null,
  "token": null,
  "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.