Best practices

General | REST APIs | SOAP APIs

General

Credentials
Alegeus APIs require a valid username and password, and a session must be obtained before calling any API operations. An error will be returned if an operation is attempted without a valid session ID.

If using the same user ID and password for all clients, you are responsible for managing the security of the data.

Avoid unnecessary calls
Cache data when possible. [Caching policies coming soon!]. Do not utilize APIs for bulk usage. Our APIs are currently designed for incremental, “on-demand” real-time integration. If batch processing is required, then the Data Exchange process should be used.

Use the right API products for what you're trying to do
The administrative APIs and participant APIs utilize different settings for returning responses.  Using an inappropriate set of APIs could have unexpected and undesired results.

Code to error codes, not error descriptions
We are constantly working to improve our error messaging to make troubleshooting easier for you. This means that the error message text will change over time.  If your program responds to error codes, you will not need to make development updates when we change our error message text. To make it easier for your team, we recommend logging the error message text in case there is a need to research an issue.

Validate data before submitting requests
This facilitates better performance and accurate processing on both systems.

REST APIs

Access control
Alegeus recommends utilizing a different REST user configuration on a "per platform" basis.  That is, if you are calling REST APIs to drive multiple channels (i.e., portal, mobile, IVR), have each channel use a different user ID. 

This is beneficial for audit and security reasons:

• Using multiple user ids supports the principle of least privilege. Each part of your platform should only be given the least amount of permissions necessary to perform its function.

• If you need to research an incident, you can use the user ID that did the activity to determine the channel through which the activity was completed.

• If one user ID is compromised or blocked for any reason, end users will still be able to access the other channels.

SOAP APIs

Concurrent Requests
A concurrent request is defined as two or more HTTP/SOAP requests made by a client at the same time, usually by creating separate threads on the client’s machine. Concurrent requests on your system jeopardize API performance for other clients, as they have potential to overload the server, which may slow it down or even cause it to crash. For this reason, Alegeus limits the amount of allowed concurrent requests per session.

In the event that a client sends too many concurrent requests, a SOAP fault such as the following example, is returned describing the problem:

<SOAP-ENV:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:clr="http://schemas.microsoft.com/soap/encoding/clr/1.0"
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body>
<SOAP-ENV:Fault>
<faultcode>SOAP- ENV:http://schemas.xmlsoap.org/soap/envelope/:Client</faultcode>
<faultstring>Toomany concurrent requests</faultstring>
<faultactor>http://medibank.com/MBIWebServices/Transactions/Services/Adjudicat ionService.asmx</faultactor>
<detail>Only 1 concurrent connections are allowed.</detail>
</SOAP-ENV:Fault>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Session Management
In order to call the majority of Alegeus SOAP service operations, you must pass the method a valid session ID. This can be done through cookies or Alegeus’ custom SOAP header.

Below is example code for how to setup and use sessions with Alegeus web services (example client code in .NET using proxy classes):

…
localhost.Service1 proxy = new localhost.Service1(); 
if(useCookies)
{
proxy.CookieContainer= new System.Net.CookieContainer();
proxy.LogOn("username","password")
} 
else
{ 
localhost.MBISessionHeadersession = new localhost.MBISessionHeader(); 
session.MBISessionID= proxy.LogOn("username","password"); 
proxy.MBISessionHeaderValue= session;
}
MessageBox.Show(proxy.HelloWorld())
proxy.logOut();

The following is an example of a SOAP message with the custom WCA session included in the header:

<soap:Envelope xmlns:soap=http://schemas.xmlsoap.org/soap/envelope/ xmlns:xsi=”http://www.w3.org/2001/SMLSchemainstance xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Header>
<MBISessionHeader xmlns="http://www.mbicard.com/webservices/">
<MBISessionID>up5f3n55ompe5t45l4oxak45</MBISessionID>
</MBISessionHeader>
</soap:Header>
<soap:Body>
<HelloWorld xmlns="http://www.mbicard.com/webservices/" />
</soap:Body>
</soap:Envelope>"

Alegeus limits the number of concurrent sessions per administrator.
The following is an example of the error returned when a client attempts to start too many concurrent sessions:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> 
<soap:Header>
<MBIMessageIdHeaderxmlns="http://www.medibank.com/MBIWebServices/SoapHeader/">
<MessageId>dced9719-ea9d-431d-89b8-616b3aaa0faa</MessageId></MBIMessageIdHeader> 
</soap:Header> 
<soap:Body> 
<soap:Fault>
<faultcode>soap:Client</faultcode>
<faultstring>System.Web.Services.Protocols.SoapException: Too many sessions.</faultstring>
<detail>
<mbiExceptionsxmlns="http://www.medibank.com/MBIWebServices/SoapFault/">
<mbiException>
<code>100905</code>
<message>Toomany sessions.</message>
</mbiException>
</mbiExceptions>
</detail>
</soap:Fault>
</soap:Body>
</soap:Envelope>