Calling an API #

Some APIs can be available, especially to modify information from a third party application.

The identification is managed by a login and a token, to be provided during the call among the variables. For more information about the creation of a dedicated account and the generation of the token, see the following document Identification for web services

Example of call in PHP #

class ApiCurlException extends Exception{};
/**
 * call a api with curl
 * code from
 * @param string $method
 * @param string $url
 * @param array $data
 * @return void
 */
function apiCall($method, $url, $certificate_path = "", $data = array(), $modeDebug = false)
{
  $curl = curl_init();
  if (!$curl) {
    throw new ApiCurlException(_("Impossible d'initialiser le composant curl"));
  }
  switch ($method) {
    case "POST":
      curl_setopt($curl, CURLOPT_POST, true);
      if (!empty($data)) {
        curl_setopt($curl, CURLOPT_POSTFIELDS, $data);
      }
      break;
    case "PUT":
      curl_setopt($curl, CURLOPT_CUSTOMREQUEST, "PUT");
      if (!empty($data)) {
        curl_setopt($curl, CURLOPT_POSTFIELDS, $data);
      }
      break;
    default:
      if (!empty($data)) {
        $url = sprintf("%s?%s", $url, http_build_query($data));
      }
  }
  /**
   * Set options
   */
  curl_setopt($curl, CURLOPT_URL, $url);
  curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);

  if (!empty($certificate_path)){
    curl_setopt($curl, CURLOPT_SSLCERT, $certificate_path);
  }
  if ($modeDebug) {
    curl_setopt($curl, CURLOPT_SSL_VERIFYSTATUS, false);
    curl_setopt ($curl, CURLOPT_SSL_VERIFYPEER, false);
    curl_setopt($curl,CURLOPT_SSL_VERIFYHOST, 0 );
    curl_setopt($curl, CURLOPT_VERBOSE, true);
  }
  /**
   * Execute request
   */
  $res = curl_exec($curl);
  if (!$res) {
    throw new ApiCurlException(sprintf(_("Une erreur est survenue lors de l'exécution de la requête vers le serveur distant. Code d'erreur CURL : %s"), curl_error($curl)));
  }
  curl_close($curl);
  return $res;
}

Parameters #

• method: GET, POST, PUT, DELETE (not implemented in the function). For postings, it is better to indicate POST, and to keep GET only to get information about an item. The PUT method is treated like the POST method.
• url: address of the API, for example collec.mysociety.com/index.php?module=apiv1sampleWrite
• certificate_path : path to the certificate of the remote server. In production, the certificate must be valid and generated by a certification authority recognized by your server
• data: array containing all the variables to be transmitted to the server. This table must contain :
  • login: the login of the account authorized to use the API
  • token: the token associated to this account
• modeDebug: if at true, the certificate checks are inhibited. Never use in production !

Example of call #

This example is used in the metabo application, and allows to create a sample in a Collec-Science instance.

$uidMin = 99999999;
	      $uidMax = 0;
	      try {
	        if (empty($_POST["samples"])) {
	          throw new SampleException(_("Aucun échantillon n'a été sélectionné"));
	        }
	        /**
	         * Verify the parameters for Collec-science
	         */
	        if (empty($_SESSION["collec_token"]) || empty($_SESSION["collec_sample_address"] || empty($_SESSION["collec_login"]))) {
	          throw new SampleException(_("Les paramètres pour Collec-Science n'ont pas été renseignés"));
	        }
	        foreach ($_POST["samples"] as $sample_id) {
	          $dataClass->auto_date = 0;
	          $dataSample = $dataClass->getDetail($sample_id);
	          if (empty($dataSample["uuid"])) {
	            throw new SampleException(sprintf(_("Impossible de lire les informations de l'échantillon %s"), $sample_id));
	          }
	          if (!projectVerify($dataSample["project_id"])) {
	            throw new SampleException(sprintf(_("Vous ne disposez pas des droits nécessaires sur l'échantillon %s"), $sample_id));
	          }
	          $data = array();
	          $data["sample_type_name"] = $dataSample["collec_type_name"];
	          $data["sampling_date"] = $dataSample["sampling_date"];
	          $data["identifier"] = $dataSample["sample_name"];
	          $data["uuid"] = $dataSample["uuid"];
	          $data["station_name"] = $dataSample["station_name"];
	          $data["wgs84_x"] = $dataSample["wgs84_x"];
	          $data["wgs84_y"] = $dataSample["wgs84_y"];
	          $data["token"] = $_SESSION["collec_token"];
	          $data["login"] = $_SESSION["collec_login"];
	          $debugMode = true;
	          $result_json = apiCall("POST", $_SESSION["collec_sample_address"], "", $data, $debugMode);
	          $result = json_decode($result_json, true);
	          if ($result["error_code"] != 200) {
	            throw new SampleException(sprintf(_("L'erreur %1\$s a été générée lors du traitement de l'échantillon %3\$s : %2\$s"), $result["error_code"], $result["error_message"] . " " . $result["error_detail"], $sample_id));
	          }
	          $uid = $result['uid'];
	          if ($uid > 0) {
	            if ($uid < $uidMin) {
	              $uidMin = $uid;
	            }
	            if ($uid > $uidMax) {
	              $uidMax = $uid;
	            }
	          }
	        }
	        $module_coderetour = 1;
	      } catch (Exception $e) {
	        $message->set($e->getMessage(), true);
	        $module_coderetour = -1;
	      } finally {
	        if ($uidMax > 0) {
	          $message->set(sprintf(_("UID min traité : %s"), $uidMin));
	          $message->set(sprintf(_("UID max traité : %s"), $uidMax));
	        }
	      }

Translated with www.DeepL.com/Translator (free version)