Spécifications des échanges REST

Les Web Services utilisent les principes communs des API REST. Le format d'échange utilisé est le JSON.

Authentification

L'API REST utilise l'authentification basique. Pour plus d'information, rendez-vous ici: Phase d'authentification. Pour retrouvez vos clés, consultez l'article suivant: Prérequis.

Paramètres de la requête

L'application attend un JSON valide comme entrée de requête. Par exemple, Charge/SDKTest interprétera Type/String object comme valeur d'entrée.

L'appel doit être effectué comme suit :

/doc/fr-FR/rest/V4.0/api/kb/authentication.html

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

https://api-clicandpay.groupecdn.fr/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);

Paramètres de la réponse

Quand le Web Service répond, il retourne :

{
    "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":"CDN",
    "metadata":null,
    "_type":"V4/WebService/Response"
}

L'objet demandé est retourné dans un objet de réponse générique où :

PARAMÈTRES	TYPE	DESCRIPTION
webService	chaine	web-service appelé, format: [namespace]/[web_service_name]
version	chaine	version de l'API
status	chaine	statut de la réponse: SUCCESS ou ERROR
answer	objet	la réponse metier (if status is SUCCESS)
ticket	chaine	numéro de ticket a transmettre au support (non implémenté)
applicationProvider	chaine	plateforme qui délivre le service
applicationVersion	chaine	version de l'application
metadata	objet	réservé à usage interne
serverDateTime	chaine	date du serveur qui a répondu, en UTC
_type	chaine	type de l'objet. commence toujours par le numero de version

Gestion des erreurs

En cas d'erreur du Web Service :

/doc/fr-FR/rest/V4.0/api/kb/authentication.html

https://api-clicandpay.groupecdn.fr/api-payment/V4/Charge/CreatePayment

{
    "amount": -1
}

La réponse est :

{
	"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"
}

Le Web Service a échoué et retourne un objet WebService/WebServiceError :

PARAMETRE	TYPE	DESCRIPTION
errorCode	chaine	Code d'erreur (au format [PREFIXE]_[CODE])
errorMessage	chaine	Message d'erreur
detailedErrorCode	chaine	Code d'erreur détaillé (ou null)
detailedErrorMessage	chaine	Message détaillé (ou null)

Pour plus de détails sur les erreurs, rendez-vous ici: Codes d'erreur.

Pourquoi l'API n'est elle pas 100% RESTful ?

Nous avons décidé de développer une API aussi simple que possible pour éviter les erreurs communes:

Nous utilisons seulement la méthode POST.

Ainsi nous évitons les questions habituelles à propos de quelle méthode utiliser, c'est TOUJOURS POST.

Tous les paramètres de requête sont envoyés sous la forme d'un objet JSON:

Il n'y a qu'une seule façon d'envoyer des paramètres (rien n'est ajouté dans l'URI).
Les journaux sont plus simples.
L'API répond toujours HTTP 200

Donc pas de nécessité de gérer plusieurs codes de statut HTTP, la réponse est toujours 200. Le statut du Web Service peut être consulté à l'intérieur de l'objet JSON.

Date et heure

L'objet datetime est au format ISO 8601.

Le Web Service accepte tous les fuseaux horaires tels que :

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

Le serveur retourne toujours l'objet datetime à l'heure UTC (GMT+00) :

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

Le serveur ne retourne jamais 2015-11-19T16:56:57+Z

Valeurs nulles

Les valeurs nulles non obligatoires sont automatiquement absentes de la réponse. Autrement dit, une propriété nulle est incluse dans la réponse si et seulement si la clef est rendue obligatoire, et null en est une valeur acceptable.

Catégories

Tags