SecuTix standards for web services (SOAP)

1. Technologies

Web Services use the SOAP 1.1 technology (http://www.w3.org/TR/soap/).

2. Data transport

If the client identifies itself as the supporting via the header HTTP Accept-Encoding : gzip,deflate, the response will be compressed.

3. Load limitation

In order to ensure good system reactivity, a load limiter is implemented. If not specified otherwise in the service documation, a limit of 60 requets per minutes on all APIs of a given institution for a given endpoint is set, the exceeding ones being rejected by an HTTP-509 response.

Should you want to increase this limit, plesae contact api-support@secutix.com (this will be a paying service)

4. Security

Messages security is guaranteed by the complementary use of the TLS and of the WS-Security standard (http://www.oasis-open.org/committees/wss/ ).

4.1. Authentication

To authenticate the calling system, we use the UserToken with a login and password in the message’s header, as defined in the WS-Security standard (http://www.oasis-open.org/committees/wss/documents/WSS-Username-02-0223-merged.pdf ).

Example of security header:

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
  <S:Header>
...
    <wsse:Security>
      <wsse:UsernameToken>
        <wsse:Username>INSTIT_ZOE</wsse:Username>
        <wsse:Password>ILoveDogs</wsse:Password>
      </wsse:UsernameToken>
    </wsse:Security>
...
  </S:Header>
...
</S:Envelope>

Important notice:

The login and passwords provided by SecuTix are confidential and need to be secured by the partner to whom they are provided.

PHP connection example with authentication
Download example here: soap.zip

This code is delivered as an example, is not production ready and will neither be maintained nor supported.

4.2. Data confidentiality

The use of TLS guarantees the confidentiality and integrity of the data transmitted on the internet. From of client standpoint, the only need is to have an http client able to call Web Services via https://

4.3. Access to Web Services

Web Services are accessible via the following URL:

https://XXXXX.ws.secutix.com/path/ service

Each service’s wsdl can be accessed by adding “?wsdl” to the service’s URL:

https://XXXXX.ws.secutix.com/path/ service?wsdl

Please note: the service’s version is part of the service path

5. General principle

All services follow the same convention. An answer always includes a technical status as well as “business” data when those can be sent back.

Unless otherwise specified, all methods are transactionnal and idempotent.

5.1 Response status

A response always includes the following elements (WebMethodResult):

Name Type Description
statusCode String This status code tells whether the request has been correctly implemented. List of codes here.
statusDetail String Error message that explains the cause of the problem.
requestId Integer Request identifier. Is only useful when the response indicates statusCode=in_progress

5.2. Synchronous / asynchronous response

When statusCode is success, the request is complete. The requested data are included in the response. Most of the calls are always synchronous.


result = secuTixWebService.callOneMethod(null,param1,param2);

if(result.getStatusCode().equals("success")) {
    //process normal behavior
} else {
    //process error.
}

When executing a call which duration exceed 30s, SecuTix may return in_progress as status code along with a requestId. In that case, the calling code must wait a few seconds and call again passing along the requestId.

result = secuTixWebService.callOneMethod(null,param1,param2);

while(result.getStatusCode().equals("in_progress")){
    wait(30); //wait 30 secondes
    result = secuTixWebService.callOneMethod(result.getRequestId(),param1,param2);

}

if(result.getStatusCode().equals("success")) {
    //process normal behavior
} else {
    //process error.
}

5.3. Internationalisation

If the response includes some fields that are defined as multilingual values in the system’s configuration, then:

For catalogue’s methods (which reflect the configuration), the multilingual value will be returned For action methods where the value is returned to avoid having to look into the configuration before responding to the client, only a chain of characters is being returned in the default locale being chosen (in order): By the HTTP header Accept-Language according to the RFC The default language of the institution.

5.4. Business data

This document presents “conceptual” descriptions of “business” data returned by a service, in the sense that they represent the semantics of the methods and objects. Syntax is voluntarily simplified in order to ease the reading and understanding. The real syntax is described in the generated WSDL.

All numerical Ids have to be considered, by default, as being on 64bits.

Monetary amounts are provided as longs, hence they must be divided by 1000 to get the actual value.

5.5. Versions management

Each service’s version is made of a major and minor number: X.Y

X is incremented in a non-backward-compatible change Y is incremented in a backward-compatible change (adding methods, etc.) The version number is directly included in the service’s URL and can also be found in the name space of the WSDL file.

5.6. Monitoring

In order to carry out a proactive monitoring of the connectivity between the access control system and SecuTix, each service has a calling method:

WebMethodResult isXXXAlive();

With XXX being the service name.

This method validates the network connection as well as the login and password.

The recommended frequency is 5 to 10 minutes.