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 i-Tego SaaS).
Exemple :
https://login:password@qrc.dnc.global/api/json/qrcodesOpé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/1retourne :
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/33où 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 :
$path_parameters = "json/qrcode";
$query_parameters = array(
'id_auteur' => '1', // SPIP administrator
'titre' => $titre,
'url_cible' => $url_cible,
'statut' => 'publie'
); et voici la fonction :
function http_request( $apiurl, $method, $path_parameters=null, $query_parameters=null ) {
$url = $apiurl . $path_parameters;
$h = curl_init($url);
if ( !empty($query_parameters) )
curl_setopt($h, CURLOPT_POSTFIELDS, json_encode($query_parameters));
if ( $method == "POST" ) {
$header[] = "content-type: application/json";
} else if ( $method !== "GET" ) {
curl_setopt($h, CURLOPT_CUSTOMREQUEST, $method);
}
curl_setopt($h, CURLOPT_FOLLOWLOCATION, true);
curl_setopt($h, CURLOPT_RETURNTRANSFER, true);
curl_setopt($h, CURLOPT_TIMEOUT, 10);
curl_setopt($h, CURLOPT_HTTPHEADER, $header);
$result = curl_exec($h);
curl_close($h);
return $result;
}