API HTTP Rest

, par DnC

zQR-Codes expose une API HTTP Rest.

Accéder à l’API

L’accès à l’API est limité au cadre d’un abonnement donné. L’abonnement doit être valide.

L’accès à l’API nécessite donc de fournir dans la requête les identifiants de l’utilisateur (login et password utilisés pour la connexion à l’application zQR-Codes avec DnC SaaS).

Exemple :

https://login:password@qrc.dnc.global/api/json/qrcodes

Opérations permises par l’API

L’API permet à un utilisateur d’effectuer les opérations CRUD sur la table des QR-Codes en fonction de la méthode de la requête HTTP GET, POST, PUT ou DELETE :

Formats

Dans l’état actuel du développement, l’API de O-DGuide n’expose que le format suivant :

Format json
Retourne un simple array. Exemple : la requête :

https://qrc.dnc.global/api/json/qrcode/1

retourne :

  1.  

Types

Dans l’état actuel du développement, l’API de O-DGuide n’expose que le type ’qrcode’.

Actions

Suivant le paradigme HTTP Rest, les actions découlent de la méthode HTTP utilisée pour appeler l’API : get, post, put ou delete.

Formes générales des requêtes
Une requête GET prend la forme :
https://qrc.dnc.global/api/[path_parameters] | [?request_parameters]

 path_parameters : /[/ressource]
généralement ce sera : json/qrcode, NN indiquant l’ID d’un QR-Code précis.

 query_parameters : dans le cas de GET, il s’agit des classiques paramètres d’URL, tels que "url_cible=https://mon_site.com/blabla.php".

Exemple de requêtes GET
 Afficher la liste des QR-Codes disponibles pour l’auteur authentifié :

https://qrc.dnc.global/api/json/qrcode

 Accès à une ressource précise :

https://qrc.dnc.global/api/json/qrcode/33

où 33 est l’ID de ressource, en l’occurrence la valeur du champ id_qrcode de l’enregistrement dans la table.

Requêtes avec POST, PUT et DELETE

Ces requêtes doivent être générées programmatiquement : par exemple avec cURL côté serveur ou en Javascript côté client. On trouve couramment des bibliothèque exposant des fonctions de ce type :

 post_collection($requete, $reponse)
Créer une nouvelle ressource dans la collection (créer un nouvel enregistrement dans la table).

 put_ressource($requete, $reponse)
Ce cas est sensiblement le même que le précédent, à ceci près que l’on travaille sur la modification d’une ressource précise.

 delete_ressource($requete, $reponse)
Supprimer définitivement une ressource.

Pour la transmission des données aux requêtes avec POST et PUT, on applique le format application/json. Dans l’exemple qui suit, on passe deux tableaux PHP, la fonction se chargeant de l’encodage JSON et de la déclaration. On passe les paramètres de la façon suivante :

  1. $path_parameters = "json/qrcode";
  2.  
  3. $query_parameters = array(
  4.         'id_auteur' => '1',    // SPIP administrator
  5.         'titre' => $titre,
  6.         'url_cible' => $url_cible,
  7.         'statut' => 'publie'    
  8.     );

Télécharger

et voici la fonction :

  1. function http_request( $apiurl, $method, $path_parameters=null, $query_parameters=null ) {
  2.  
  3.         $url = $apiurl . $path_parameters;
  4.         $h = curl_init($url);
  5.         if ( !empty($query_parameters) )
  6.             curl_setopt($h, CURLOPT_POSTFIELDS, json_encode($query_parameters));  
  7.         if ( $method == "POST" ) {
  8.             $header[] = "content-type: application/json";  
  9.         } else if ( $method !== "GET" ) {
  10.             curl_setopt($h, CURLOPT_CUSTOMREQUEST, $method);
  11.         }
  12.         curl_setopt($h, CURLOPT_FOLLOWLOCATION, true);
  13.         curl_setopt($h, CURLOPT_RETURNTRANSFER, true);
  14.         curl_setopt($h, CURLOPT_TIMEOUT, 10);
  15.         curl_setopt($h, CURLOPT_HTTPHEADER, $header);  
  16.  
  17.         $result = curl_exec($h);
  18.         curl_close($h);
  19.  
  20.         return $result;
  21.  
  22. }

Télécharger