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

Jump to: navigation, search
[unchecked revision][unchecked revision]
(HTTP Request)
 
 
(10 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
__NOTOC__
 
__NOTOC__
Access to the Management API is provided by the HTTP server of the MailStore Service Provider Edition Management Server which listens on TCP port 8470 by default. All communication is SSL encrypted.
 
  
Each request to the Management API must be authenticated by sending a valid cookie and to prevent cross-site request forgery (XSRF) a valid ''X-AntiXsrfToken'' HTTP-header. Such a cookie and token is created after successfully logging on. The cookie's lifetime is extended with each new request to the API and each request creates a new unique anti XSRF token to be used in the subsequent request. Each request must be of the type POST.
+
Access to the Management API is provided by the HTTP server of the MailStore Service Provider Edition Management Server which listens on TCP port 8474 by default. All communication is SSL encrypted.
 +
 
 +
Each request to the Management API must be authenticated by sending username and password following the standards for HTTP basic authentication as defined 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.
 
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.
Line 8: Line 9:
 
Refer to [[Management_API_-_Function_Reference|Function Reference]] for a full list of available API functions.
 
Refer to [[Management_API_-_Function_Reference|Function Reference]] for a full list of available API functions.
  
'''Please note:''' Depending on the scope of the called function, the URL may vary (<tt>/</tt>, <tt>/api/</tt> or <tt>/api/invoke</tt>). Please carefully check to which URL you are sending your requests in case of unexpected results.
+
'''Please note:''' Depending on the scope of the called function, the URL may vary (<tt>/api/</tt> or <tt>/api/invoke</tt>). Please carefully check to which URL you are sending your requests in case of unexpected results.
 
 
= Logging On =
 
 
 
For logging on to the Management API and requesting the authentication cookie and anti XSRF token, send a HTTP POST request to the following URL:
 
 
 
<tt><nowiki>https://<mgmt-server>:8470/login</nowiki></tt>
 
 
 
The below POST variables are expected:
 
 
 
{| class="wikitable"
 
! width=80px | Name
 
! Description
 
|-
 
| <tt>u</tt>
 
| Username of MailStore Service Provider Edition Administrator
 
|-
 
| <tt>p</tt>
 
| Password of MailStore Service Provider Edition Administrator
 
|}
 
 
 
On successful authentication ''+OK'' followed by the anti XSRF token value is returned as a normal string in the body of the HTTP response.
 
 
 
== Example ==
 
 
 
=== HTTP Request ===
 
<source lang="xml" toolbar="false" gutter="false">
 
POST /login 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: */*
 
Content-Length: 18
 
Content-Type: application/x-www-form-urlencoded
 
 
u=admin&p=Passw0rd
 
</source>
 
 
 
=== 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: 51
 
Content-Type: text/plain; charset=utf-8
 
Expires: Wed, 22 Jan 2014 14:31:34 GMT
 
Server: Microsoft-HTTPAPI/2.0
 
Set-Cookie: MSWEB_MGM_AUTH=TUidNy4lYFU03ekOUju7udiC1AfxYRCmX%2bb
 
QCGFkbWlu;path=/;secure;HttpOnly
 
Date: Thu, 23 Jan 2014 14:31:34 GMT
 
 
+OK Lj9SUpcVnVv5t938IgJNgFiAZsLxYRCmX+bQCGFkbWlu
 
</source>
 
 
 
= Logging Out =
 
 
 
For logging out of the Management API and expire the authentication cookie immediately, send an empty HTTP POST request to the following URL:
 
 
 
<tt><nowiki>https://<mgmt-server>:8470/logout</nowiki></tt>
 
 
 
'''Important Notice:''' Depending on the HTTP client library in use, the HTTP Content-Length header might not get set for empty HTTP POST requests. In that case it is required to set ''Content-Length: 0'' manually in the HTTP header. Also the HTTP client library might follow HTTP 302 redirects automatically. In this case the MailStore log in page will be presented instead of the response mentioned below.
 
  
== Example ==
+
== Executing Regular API Functions ==
 
 
=== HTTP Request ===
 
<source lang="xml" toolbar="false" gutter="false">
 
POST /logout 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=TUidNy4lYFU03ekOUju7udiC1AfxYRCmX%2bb
 
X-AntiXsrfToken: Lj9SUpcVnVv5t938IgJNgFiAZsLxYRCmX+bQCGFkbWlu
 
Content-Length: 0
 
</source>
 
 
 
=== HTTP Response ===
 
<source lang="xml" toolbar="false" gutter="false">
 
HTTP/1.1 302 Found
 
Cache-Control: no-cache,private,no-store,must-revalidate,max-stale=0,post-check=0,pre-check=0
 
Pragma: no-cache
 
Content-Length: 47
 
Content-Type: text/html; charset=utf-8
 
Expires: Wed, 22 Jan 2014 14:27:56 GMT
 
Location: /web/login.html
 
Server: Microsoft-HTTPAPI/2.0
 
Set-Cookie: MSWEB_MGM_AUTH=;path=/;secure;HttpOnly
 
Date: Thu, 23 Jan 2014 14:27:56 GMT
 
 
<html><body><h1>302 Found</h1></body></html>
 
</source>
 
 
 
= Executing Regular API Functions =
 
  
 
To execute regular Management API functions, send HTTP POST request to the following URL:
 
To execute regular Management API functions, send HTTP POST request to the following URL:
  
<tt><nowiki>https://<mgmt-server>:8470/api/invoke/<function></nowiki></tt>
+
<tt><nowiki>https://<mgmt-server>:8474/api/invoke/<function></nowiki></tt>
 
 
Do not forget to send the cookie and the latest anti XSRF token along with each request. This extends the cookie lifetime and returns a valid anti XSRF token for the next request. The token value can be extracted from the ''antiXsrfToken'' key of the returned JSON string.
 
  
== Example ==
+
=== Example ===
  
=== HTTP Request ===
+
==== HTTP Request ====
 
<source lang="xml" toolbar="false" gutter="false">
 
<source lang="xml" toolbar="false" gutter="false">
 
POST /api/invoke/GetEnvironmentInfo HTTP/1.1
 
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
+
Authorization: Basic YWRtaW46UGFzc3cwcmQ=
Host: dweuthen.mscloud.test:8470
+
User-Agent: curl/7.35.0
 +
Host: spe.example.com:8474
 
Accept: */*
 
Accept: */*
Cookie: MSWEB_MGM_AUTH=TUidNy4lYFU03ekOUju7udiC1AfxYRCmX%2bb
 
X-AntiXsrfToken: Lj9SUpcVnVv5t938IgJNgFiAZsLxYRCmX+bQCGFkbWlu
 
 
Content-Length: 0
 
Content-Length: 0
Content-Type: application/x-www-form-urlencoded
+
 
 
</source>
 
</source>
  
=== HTTP Response ===
+
==== HTTP Response ====
 
<source lang="xml" toolbar="false" gutter="false">
 
<source lang="xml" toolbar="false" gutter="false">
 
HTTP/1.1 200 OK
 
HTTP/1.1 200 OK
 
Cache-Control: no-cache,private,no-store,must-revalidate,max-stale=0,post-check=0,pre-check=0
 
Cache-Control: no-cache,private,no-store,must-revalidate,max-stale=0,post-check=0,pre-check=0
 
Pragma: no-cache
 
Pragma: no-cache
Content-Length: 770
+
Content-Length: 798
 
Content-Type: application/json
 
Content-Type: application/json
Expires: Wed, 22 Jan 2014 15:05:19 GMT
+
Expires: Wed, 25 Jun 2014 13:50:53 GMT
 
Server: Microsoft-HTTPAPI/2.0
 
Server: Microsoft-HTTPAPI/2.0
Set-Cookie: MSWEB_MGM_AUTH=Ecru%2fvKOOd1TdbClcEdWAigiRu%2fCJA5dZObQCGFkbWlu;path=/;secure;HttpOnly
+
Date: Thu, 26 Jun 2014 13:50:53 GMT
Date: Thu, 23 Jan 2014 15:05:19 GMT
+
 
 
 
{
 
{
  "error": null,
+
  "error": null,
  "token": null,
+
  "token": null,
  "antiXsrfToken": "RPDV65bC7Jap57JwtjvhOBlPBEDCJA5dZObQCGFkbWlu",
+
  "statusVersion": 2,
  "statusVersion": 2,
+
  "statusCode": "succeeded",
  "statusCode": "succeeded",
+
  "percentProgress": null,
  "percentProgress": null,
+
  "statusText": null,
  "statusText": null,
+
  "result": {
  "result": {
+
    "version": "9.0.0.9672",
    "version": "8.5.0.9272",
+
    "copyright": "Copyright (c) 2005-2014 MailStore Software GmbH",
    "copyright": "Copyright (c) 2005-2013 MailStore Software GmbH",
+
    "licenseeName": "MailStore Software GmbH",
    "licenseeName": "MailStore Software GmbH",
+
    "licenseeID": 10510,
    "licenseeID": 10510,
+
    "serverName": "spe.example.com",
    "serverName": "server.ms-spe.test",
+
    "userName": "admin",
    "userName": "admin",
+
    "systemProperties": {
    "systemProperties": {
+
      "processors": [
      "processors": [
+
        "Intel(R) Xeon(R) CPU E5645 @ 2.40GHz",
        "Intel(R) Xeon(R) CPU E5645 @ 2.40GHz",
+
        "Intel(R) Xeon(R) CPU E5645 @ 2.40GHz",
        "Intel(R) Xeon(R) CPU E5645 @ 2.40GHz"
+
        "Intel(R) Xeon(R) CPU E5645 @ 2.40GHz",
      ],
+
        "Intel(R) Xeon(R) CPU E5645 @ 2.40GHz"
      "totalPhysicalMemory": 4398800896,
+
      ],
      "operatingSystem": "Microsoft Windows Server 2012 Standard"
+
      "totalPhysicalMemory": 12884430848,
 +
      "operatingSystem": "Microsoft Windows Server 2012 Standard"
 
     }
 
     }
  },
+
  },
  "logOutput": null
+
  "logOutput": null
}
+
}
 
</source>
 
</source>
  
= Long Running Processes =
+
To get a list of all available functions, send a POST request to <nowiki>https://<mgmt-server>:8474/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.  
 
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:
 
The overall process is as follows:
  
# Send HTTP POST to <tt><nowiki>https://<mgmt-server>:8470/api/invoke/VerifyStore</nowiki></tt> in order to execute the function.<br/>
+
# Send HTTP POST to <tt><nowiki>https://<mgmt-server>:8474/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/>
 
# 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://<mgmt-server>:8470/api/get-status</nowiki></tt> with the following parameters:<br/>
+
# To retrieve status updates, send periodic requests to <tt><nowiki>https://<mgmt-server>:8474/api/get-status</nowiki></tt> with the following parameters:<br/>
 
{| class="wikitable" style="margin-left:35px"
 
{| class="wikitable" style="margin-left:35px"
 
! Name
 
! Name
Line 184: Line 95:
 
: 4. The process finished when the <tt>statusCode</tt> is not ''running''.
 
: 4. The process finished when the <tt>statusCode</tt> is not ''running''.
  
== Example ==
+
=== Example ===
  
=== Initial HTTP Request ===
+
==== Initial HTTP Request ====
 
<source lang="xml" toolbar="false" gutter="false">
 
<source lang="xml" toolbar="false" gutter="false">
 
POST /api/invoke/VerifyStore HTTP/1.1
 
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
+
Authorization: Basic YWRtaW46UGFzc3cwcmQ=
Host: server.ms-spe.tesst:8470
+
User-Agent: curl/7.35.0
 +
Host: spe.example.com:8474
 
Accept: */*
 
Accept: */*
Cookie: MSWEB_MGM_AUTH=ZsByPD0aV4gYcGt3DL6elnMSKAaQTyRe%2fqHQCGFkbWlu
+
Content-Length: 24
X-AntiXsrfToken: BTp4ZWF5n8sDDpI0LG5z5bKYIzakLfzubebQCGFkbWlu
 
Content-Length: 28
 
 
Content-Type: application/x-www-form-urlencoded
 
Content-Type: application/x-www-form-urlencoded
 
+
instanceID=i20140122-01&id=2
+
instanceID=adsolver&id=1
 
</source>
 
</source>
  
=== Initial HTTP Response ===
+
==== Initial HTTP Response ====
 
<source lang="xml" toolbar="false" gutter="false">
 
<source lang="xml" toolbar="false" gutter="false">
 
HTTP/1.1 200 OK
 
HTTP/1.1 200 OK
Cache-Control: no-cache,private,no-store,must-revalidate,max-stale=0,post-check=0,pre-check=0
+
Cache-Control: no-cache,private,no-store,must-revalidate,max-stale=0,postcheck=0,pre-check=0
 
Pragma: no-cache
 
Pragma: no-cache
Content-Length: 359
+
Content-Length: 291
 
Content-Type: application/json
 
Content-Type: application/json
Expires: Wed, 22 Jan 2014 16:13:50 GMT
+
Expires: Wed, 25 Jun 2014 14:03:45 GMT
 
Server: Microsoft-HTTPAPI/2.0
 
Server: Microsoft-HTTPAPI/2.0
Set-Cookie: MSWEB_MGM_AUTH=wG332pdxKrKEbmAvsc81kOja7QOG7wDvbebQCGFkbWlu;path=/;secure;HttpOnly
+
Date: Thu, 26 Jun 2014 14:03:45 GMT
Date: Thu, 23 Jan 2014 16:13:49 GMT
 
 
   
 
   
 
{
 
{
 
   "error": null,
 
   "error": null,
   "token": "sa71c6ef0d880a14eb2220fa87f276710e",
+
   "token": "sa46594cd64b35f62796c405c0ed155ee8",
  "antiXsrfToken": "Z1aU+nQNasuCl9pvKGTANHKfFuyG7wDvbebQCGFkbWlu",
 
 
   "statusVersion": 3,
 
   "statusVersion": 3,
 
   "statusCode": "running",
 
   "statusCode": "running",
Line 221: Line 129:
 
   "statusText": null,
 
   "statusText": null,
 
   "result": null,
 
   "result": null,
   "logOutput": "Verifying file group #2...\r\nCreating a list of messages to be verified...\r\n"
+
   "logOutput": "Verifying file group #1...\r\nCreating a list of messages to be verified...\r\n"
 
}
 
}
 
</source>
 
</source>
  
=== Periodic HTTP Request of Progress ===
+
==== Periodic HTTP Request of Progress ====
 
<source lang="xml" toolbar="false" gutter="false">
 
<source lang="xml" toolbar="false" gutter="false">
 
POST /api/get-status HTTP/1.1
 
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
+
Authorization: Basic YWRtaW46UGFzc3cwcmQ=
Host: server.ms-spe.test:8470
+
User-Agent: curl/7.35.0
 +
Host: spe.example.com:8474
 
Accept: */*
 
Accept: */*
Cookie: MSWEB_MGM_AUTH=wG332pdxKrKEbmAvsc81kOja7QOG7wDvbebQCGFkbWlu
 
X-AntiXsrfToken: Z1aU+nQNasuCl9pvKGTANHKfFuyG7wDvbebQCGFkbWlu
 
 
Content-Length: 90
 
Content-Length: 90
 
Content-Type: application/x-www-form-urlencoded
 
Content-Type: application/x-www-form-urlencoded
 
   
 
   
token=sa71c6ef0d880a14eb2220fa87f276710e&lastKnownStatusVersion=3&millisecondsTimeout=5000
+
token=sa46594cd64b35f62796c405c0ed155ee8&lastKnownStatusVersion=3&millisecondsTimeout=5000
 
</source>
 
</source>
  
=== HTTP Response to Periodic Progress Requests ===
+
==== HTTP Response to Periodic Progress Requests ====
 
<source lang="xml" toolbar="false" gutter="false">
 
<source lang="xml" toolbar="false" gutter="false">
 
HTTP/1.1 200 OK
 
HTTP/1.1 200 OK
 
Cache-Control: no-cache,private,no-store,must-revalidate,max-stale=0,post-check=0,pre-check=0
 
Cache-Control: no-cache,private,no-store,must-revalidate,max-stale=0,post-check=0,pre-check=0
 
Pragma: no-cache
 
Pragma: no-cache
Content-Length: 309
+
Content-Length: 242
 
Content-Type: application/json
 
Content-Type: application/json
Expires: Wed, 22 Jan 2014 16:21:55 GMT
+
Expires: Wed, 25 Jun 2014 14:08:15 GMT
 
Server: Microsoft-HTTPAPI/2.0
 
Server: Microsoft-HTTPAPI/2.0
Set-Cookie: MSWEB_MGM_AUTH=Fo00yVkaGWgRFyhpf4KPDdDMdLrxM4AQb%2bbQCGFkbWlu;path=/;secure;HttpOnly
+
Date: Thu, 26 Jun 2014 14:08:15 GMT
Date: Thu, 23 Jan 2014 16:21:55 GMT
 
 
   
 
   
 
{
 
{
 
   "error": null,
 
   "error": null,
   "token": null,
+
   "token": "sa46594cd64b35f62796c405c0ed155ee8",
  "antiXsrfToken": "Zrt40mK3S5xIG3HOce688LZ/QCXxM4AQb+bQCGFkbWlu",
+
   "statusVersion": 9,
   "statusVersion": 4,
 
 
   "statusCode": "running",
 
   "statusCode": "running",
 
   "percentProgress": 0,
 
   "percentProgress": 0,
 
   "statusText": null,
 
   "statusText": null,
 
   "result": null,
 
   "result": null,
   "logOutput": "500047 messages are about to be verified.\r\nVerifying...\r\n"
+
   "logOutput": " 400 messages verified...\r\n"
 
}
 
}
 
</source>
 
</source>
  
=== Final HTTP Response ===
+
==== Final HTTP Response ====
 
<source lang="xml" toolbar="false" gutter="false">
 
<source lang="xml" toolbar="false" gutter="false">
 
HTTP/1.1 200 OK
 
HTTP/1.1 200 OK
Cache-Control: no-cache,private,no-store,must-revalidate,max-stale=0,postcheck=0,pre-check=0
+
Cache-Control: no-cache,private,no-store,must-revalidate,max-stale=0,post-check=0,pre-check=0
 
Pragma: no-cache
 
Pragma: no-cache
 
Content-Length: 242
 
Content-Length: 242
 
Content-Type: application/json
 
Content-Type: application/json
Expires: Tue, 29 Oct 2013 16:09:42 GMT
+
Expires: Wed, 25 Jun 2014 15:08:15 GMT
 
Server: Microsoft-HTTPAPI/2.0
 
Server: Microsoft-HTTPAPI/2.0
Set-Cookie: MSWEB_MGM_AUTH=ZsByPD0aV4gYcGt3DL6elnMSKAaQTyRe%2fqHQCGFkbWlu;path=/;secure;HttpOnly
+
Date: Thu, 26 Jun 2014 15:08:15 GMT
Date: Wed, 30 Oct 2013 16:09:41 GMT
 
  
 
{
 
{
 
   "error": null,
 
   "error": null,
 
   "token": null,
 
   "token": null,
  "antiXsrfToken": "Dg5geOu431l/5k36IXd13FlqLQ0Ki6ElcObQCGFkbWlu"
 
 
   "statusVersion": 269,
 
   "statusVersion": 269,
 
   "statusCode": "succeeded",
 
   "statusCode": "succeeded",
Line 289: Line 192:
 
</source>
 
</source>
  
= Error Handling =
+
== 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,
 
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,
  

Latest revision as of 13:41, 19 February 2015


Access to the Management API is provided by the HTTP server of the MailStore Service Provider Edition Management Server which listens on TCP port 8474 by default. All communication is SSL encrypted.

Each request to the Management API must be authenticated by sending username and password following the standards for HTTP basic authentication as defined 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.

Refer to Function Reference for a full list of available API functions.

Please note: Depending on the scope of the called function, the URL may vary (/api/ or /api/invoke). Please carefully check to which URL you are sending your requests in case of unexpected results.

Executing Regular API Functions

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

https://<mgmt-server>:8474/api/invoke/<function>

Example

HTTP Request

POST /api/invoke/GetEnvironmentInfo HTTP/1.1
Authorization: Basic YWRtaW46UGFzc3cwcmQ=
User-Agent: curl/7.35.0
Host: spe.example.com:8474
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: 798
Content-Type: application/json
Expires: Wed, 25 Jun 2014 13:50:53 GMT
Server: Microsoft-HTTPAPI/2.0
Date: Thu, 26 Jun 2014 13:50:53 GMT
 
{
  "error": null,
  "token": null,
  "statusVersion": 2,
  "statusCode": "succeeded",
  "percentProgress": null,
  "statusText": null,
  "result": {
    "version": "9.0.0.9672",
    "copyright": "Copyright (c) 2005-2014 MailStore Software GmbH",
    "licenseeName": "MailStore Software GmbH",
    "licenseeID": 10510,
    "serverName": "spe.example.com",
    "userName": "admin",
    "systemProperties": {
      "processors": [
        "Intel(R) Xeon(R) CPU E5645 @ 2.40GHz",
        "Intel(R) Xeon(R) CPU E5645 @ 2.40GHz",
        "Intel(R) Xeon(R) CPU E5645 @ 2.40GHz",
        "Intel(R) Xeon(R) CPU E5645 @ 2.40GHz"
      ],
      "totalPhysicalMemory": 12884430848,
      "operatingSystem": "Microsoft Windows Server 2012 Standard"
     }
  },
  "logOutput": null
}

To get a list of all available functions, send a POST request to https://<mgmt-server>:8474/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://<mgmt-server>:8474/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://<mgmt-server>:8474/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: spe.example.com:8474
Accept: */*
Content-Length: 24
Content-Type: application/x-www-form-urlencoded
 
instanceID=adsolver&id=1

Initial 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: 291
Content-Type: application/json
Expires: Wed, 25 Jun 2014 14:03:45 GMT
Server: Microsoft-HTTPAPI/2.0
Date: Thu, 26 Jun 2014 14:03:45 GMT
 
{
  "error": null,
  "token": "sa46594cd64b35f62796c405c0ed155ee8",
  "statusVersion": 3,
  "statusCode": "running",
  "percentProgress": 0,
  "statusText": null,
  "result": null,
  "logOutput": "Verifying file group #1...\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=sa46594cd64b35f62796c405c0ed155ee8&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": "sa46594cd64b35f62796c405c0ed155ee8",
  "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.