S-360 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

Please check this page API rate limits

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 S-360 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

As wsdl are not supposed to change (except the one of the active version, see Versionning), it is recommended to cache or store a copy of the wsdl and of the respective xsd files on caller side.

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):

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, S-360 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 S-360, 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.