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 (Clés).

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 :

{
    "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":"PAYZEN",
    "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 :

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

Le Web Service a échoué et retourne un objet V3.1/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.