S-360 standards for web services (REST)

1. Technologies

Web Services use the REST technology through POST Method (https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST).

2. Data transport

If the client identifies itself as the supporting via the header HTTP Accept-Encoding : gzip,deflate, the response will be compressed.
The header Content-Type: application/json is also required for POST requests, so the request body should match JSON format (https://www.json.org/)
For GET requests, the body is not needed and won't be processed.

3. Load limitation

Please check this page API rate limits

4. Security

Messages security is guaranteed by the complementary use of the TLS and using JWT as authentication method in the request ( https://tools.ietf.org/html/rfc7519 ).

4.1. Authentication

To authenticate the calling system, we use the JWT as Bearer token in the HTTP Authorization request header. Check https://developer.mozilla.org/es/docs/Web/HTTP/Authentication and https://tools.ietf.org/html/rfc6750 for more info.

Example of security HTTP header:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJNT1NBIiwiYXVkIjoiTU9TQV9CMkMiLCJpc3MiOiJQYXJ0bmVyIDEiLCJpYXQiOjE2MDA2OTU0ODUsImV4cCI6MTYzMjIzMTQ4MH0.jMQIXbXdswPj-_-x2C2xhhR6Wtieq5JcVfCW4ndSr1o

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.

4.1.1 JWT

The authentication is done by forging a JWT following these specs:

  • JWT Header
    • Algorithm(alg): HS256
    • Type of token(typ): JWT
  • Payload
    • Subject(sub): Institution Code
    • Audience(aud): Virtual Operator
    • Issuer(iss): Partner Name
    • Issued at(iat): Forge datetime in epoch millis. This timestamp should be less than 1 second when S-360's endpoint receives the call
    • Expiration time(exp): Expiration time of the token in epoch millis. Each token can have an expiration time of 30 seconds after the issued time.
  • Signature
    • Secret: 256-bit secret generated and provided by S-360 to each integrator.

To generate a valid JWT, you should call to the auth endpoint described in the documentation

For testing purposes, you can use our tool here

To decode and debug the JWT, you can use the tool in https://jwt.io/

Example of JWT

Encoded JWT

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJNT1NBIiwiYXVkIjoiTU9TQV9CMkMiLCJpc3MiOiJQYXJ0bmVyIDEiLCJpYXQiOjE2MDA2OTU0ODUsImV4cCI6MTYzMjIzMTQ4MH0.jMQIXbXdswPj-_-x2C2xhhR6Wtieq5JcVfCW4ndSr1o

Header

{
  "alg": "HS256",
  "typ": "JWT"
}

Payload

{
  "sub": "MOSA",
  "aud": "MOSA_B2C",
  "iss": "Partner 1",
  "iat": 1600949809,
  "exp": 1600949829
}

Secret key

your-256-bit-secret

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

Mostly REST Web Services are accessible via the following URL:

https://<institCode>.ws.secutix.com/<module>/backend-apis/<serviceName>/<version>/<method>
Example: https://mosa.demo-ws.secutix.com/tnco/backend-apis/contactInformationPublicService/v2_22/getContactData

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

Other services can be found at Swagger Documentation

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 format

The response will be served in JSON format with HTTP headers Content-type: application/json and Content-Encoding: UTF-8

5.2 Response codes

Every response will include a HTTP status code with the following meanings:

  • 401: Unauthorized. There was a problem authorizing the call. Probably the JWT is not correct or has already expired.
  • 404: Not Found. The service, version, or method is not found in the endpoint. Check the URI endpoint called.
  • 400: Bad Request. The JSON in the request's body is not correct. Maybe the structure or maybe a malformed JSON. Double check its content
  • 200: OK. Correct request. The output will be in JSON format, with the details as shown below in 5.3
  • 500: Internal Server Error. Something went wrong in S-360's side. A detailed message is provided.

5.3 Response status

A correct response (status 200) 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.4. 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.5. 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.6. 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.7. 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.