Specifications of REST data exchange

Web Services use the common principles of the REST API. The used exchange format is JSON.

Authentication

The REST API uses basic authentication. For more information, go to: Authentication phase. To learn where to find your keys, see the following article: Prerequisites.

Request parameters

The application awaits valid JSON as request entry. For example, Charge/SDKTest will interpret the Type/String object as entry value.

The call must be made as follows:

/doc/en-EN/rest/V4.0/api/kb/authentication.html

https://github.com/lyra/rest-php-examples/blob/master/www/SDKTest.php#L16-L26

https://api.secure.osb.pf/api-payment/V4/Charge/SDKTest

{
    "value": "my testing value"
}

/** 
 * Initialize the SDK 
 * Please update your keys in keys.php
 */
$client = new Lyra\Client();  

/**
 * I send test data
 */
$store = array("value" => "my testing value");
$response = $client->post("V4/Charge/SDKTest", $store);

Response parameters

When the Web Service responds, it returns:

{
    "webService":"Charge/SDKTest",
    "version":"V4",
    "applicationVersion":"4.1.2",
    "status":"SUCCESS",
    "answer": {
        "value":"my testing value",
        "_type":"V4/Type/String"
    },
    "ticket":null,
    "serverDate":"2018-10-02T16:13:57+00:00",
    "applicationProvider":"OSB",
    "metadata":null,
    "_type":"V4/WebService/Response"
}

The requested object is returned in a generic response object where:

PARAMETERS	Type	Description
webService	String	The called web service, format: [namespace]/[web_service_name].
version	String	Version of the API.
status	String	Status of the response: SUCCESS or ERROR.
answer	The	business answer
ticket	String	Ticket number to be transmitted to the support service (not implemented).
applicationProvider	String	Gateway that provides the service.
applicationVersion	String	Version of the application.
metadata	The	Reserved for future use.
serverDateTime	String	Date of the server that responded, in UTC format.
_type	String	Type of the object. Always starts with the version number.

Error handling

In case of Web Service error:

/doc/en-EN/rest/V4.0/api/kb/authentication.html

https://api.secure.osb.pf/api-payment/V4/Charge/CreatePayment

{
    "amount": -1
}

The response is:

{
	"webService": "Charge/CreatePayment",
	"version": "V4",
	"applicationVersion": "4.5.1",
	"status": "ERROR",
	"answer": {
		"errorCode": "INT_902",
		"errorMessage": "web-service input data validation error",
		"detailedErrorCode": null,
		"detailedErrorMessage": "can't decode JSON data : {\n    \"amount\":   -1,\n}",
		"ticket": "null",
		"_type": "V4/WebService/WebServiceError"
	},
	"ticket": null,
	"serverDate": "2018-12-10T19:27:32+00:00",
	"applicationProvider": "",
	"metadata": null,
	"_type": "V4/WebService/Response"
}

The Web Service has failed and returns a WebService/WebServiceError object:

Parameter	Type	Description
errorCode	String	Error code (in [PREFIX]_[CODE] format)
errorMessage	String	Error message
detailedErrorCode	String	Detailed error code (or null)
detailedErrorMessage	String	Detailed message (or null)

For more information on errors, go to: Error codes.

Why is the API not 100% RESTful?

We have decided to develop a simple API to avoid common errors:

We only use the POST method.

This way, we avoid the usual questions about which method should be used, the answer is ALWAYS POST.

All the request parameters are sent as a JSON object:

There is only one way of sending parameters (nothing is added in the URI).
The reports are simplified.
The API always responds HTTP 200.

Therefore, there is no need to manage several HTTP status codes, the answer is always 200. The Web Service status can be viewed in the JSON object.

Date and time

The datetime object is in ISO 8601 format.

The Web Service accepts all the time zones such as:

2015-11-19T16:56:57+00:00
2015-11-19T16:56:57+01:00
2015-11-19T16:56:57+Z

The server always returns the datetime object in UTC format (GMT+00):

2015-11-19T16:56:57+00:00

The server never returns 2015-11-19T16:56:57+Z

Null values

Non-mandatory null values are automatically excluded from the response. In other words, a null property is included in the response only if the key is made mandatory, null being an acceptable value.

Categories

Tags