En un post anterior vimos los conceptos básicos sobre el API de ELSERVER.COM: como listar, crear, modificar y eliminar elementos a través de llamadas HTTP. Sin embargo, no lo aplicamos a ningún lenguaje de programación en particular.
Hoy vamos a avanzar en ese sentido: vamos a ver cómo integrar llamadas al API en nuestras aplicaciones PHP.
Utilizando cURL
Para hacer llamadas HTTP vamos a utilizar la librería cURL, disponible por defecto en toda nuestra plataforma. Si nunca lo utilizaron, pueden investigar más en la documentación oficial.
Como vamos a utilizar cURL muchas veces, nos conviene armar una función que podamos usar de esta forma:
curl($method, $url, $data);
Es bastante intuitivo para qué nos servirá cada argumento:
methodindicará el método HTTP a utilizar: GET, POST, PUT o DELETE,urlserá la URL del API con la que queremos contactar,dataserá un array con los parámetros a enviar en la llamada.
Internamente, esta función se encargará de setear todas las opciones necesarias del objeto cURL, hacer la llamada y retornar el resultado convirtiendo en un array asociativo el JSON que devuelve el API.
El código de esta función podría ser así:
function curl ($method, $url, $data) {
// Convertimos el array de parametros en un query string
$data = http_build_query($data);
// y lo agregamos a la URL en caso de un GET o DELETE
if (($method === "GET") || ($method === "DELETE")) {
$url .= '?' . $data;
}
// Definimos opciones comunes a todas las llamadas
$options = array(
CURLOPT_URL => $url,
CURLOPT_CUSTOMREQUEST => $method,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HEADER => false
);
// Si es necesario, agregamos los parametros al body de la llamada
if ($data) {
$options[CURLOPT_POSTFIELDS] = $data;
}
// Ejecutamos la llamada
$call = curl_init();
curl_setopt_array($call, $options);
$response = curl_exec($call);
curl_close($call);
// Retornamos el resultado como array
return json_decode($response, true);
}
Perfecto, ya tenemos nuestra función lista. Pueden incluirla en un archivo de helpers o en alguna clase de utilidades comunes, cambiarle el nombre o modificarla como gusten, siempre y cuando tengan acceso simple a ella.
Ahora si, vamos a utilizarla para conectarnos con el API de ELSERVER.
Validando nuestro usuario
Si leyeron el post anterior, deben recordar que para toda acción del API necesitamos un permiso, una llave única que identifique a nuestro usuario: el access_token.
Vamos a obtenerlo:
$login = curl(
'GET',
'http://cloudapi.elserver.com/sso/login/',
array(
'sso' => 'miusuario@ejemplo.com',
'password' => 'miclave'
)
);
Si ejecutamos ese script y hacemos un print_r de $login, podrán ver un resultado como el siguiente:
Array
(
[access_token] => f049ef54faf3r8245de4469ebd55eb47
[sso] => miusuario@ejemplo.com
)
¡Vamos bien! Ahora sólo debemos enviar el contenido de $login['access_token'] en todas las llamadas sucesivas.
Pedidos REST
Para seguir con nuestro ejemplo clásico, empecemos por listar las casillas de correo de nuestra cuenta. Pueden hacer la siguiente prueba:
$list = curl(
'GET',
'http://cloudapi.elserver.com/email/',
array(
'access_token' => $login['access_token'],
'account' => 'micuenta.com.ar'
)
);
Cambiando el valor de account por la cuenta deseada, por supuesto.
Si todo salió bien, $list ahora contiene la respuesta que entregó el API, es decir, un array con el listado de cuentas de correo.
Ya se deben imaginar cómo funcionan los llamados de escritura:
Para agregar una casilla de correo:
$create = curl(
'POST',
'http://cloudapi.elserver.com/email/',
array(
'access_token' => $login['access_token'],
'account' => 'micuenta.com.ar',
'user' => 'testermail',
'password' => 'somepassword'
)
);
… modificarla:
$update = curl(
'PUT',
'http://cloudapi.elserver.com/email/',
array(
'access_token' => $login['access_token'],
'account' => 'micuenta.com.ar',
'user' => 'testermail',
'info' => 'Betatester',
'mailing' => 1
)
);
… o eliminarla:
$delete = curl(
'DELETE',
'http://cloudapi.elserver.com/email/',
array(
'access_token' => $login['access_token'],
'account' => 'micuenta.com.ar',
'user' => 'testermail'
)
);
Recuerden que las funciones de escritura devuelven data: 1 en caso de ser exitosas. Por lo que si en el último ejemplo el usuario pudo ser borrado, al hacer un print_r de $delete veremos:
Array
(
[data] => 1
)
Tareas avanzadas
Con esto resulta muy fácil automatizar tareas frecuentes de nuestra cuenta de hosting. Por ejemplo, podemos programar un script que active la opción de mailing para todos nuestros usuarios de correo:
// Obtenemos nuestro access token
$login = curl(
'GET',
'http://cloudapi.elserver.com/sso/login/',
array(
'sso' => 'miusuario@ejemplo.com',
'password' => 'miclave'
)
);
// Definimos nuestra cuenta y la URL del API
$account = 'micuenta.com.ar';
$url = 'http://cloudapi.elserver.com/email/';
// Obtenemos el listado de casillas de correo
$emails = curl(
'GET',
$url,
array(
'access_token' => $login['access_token'],
'account' => $account
)
);
// Recorremos el listado activando el mailing
foreach ($emails['data'] as $email) {
$result = curl(
'PUT',
$url,
array(
'access_token' => $login['access_token'],
'account' => $account,
'user' => $email['user'],
'mailing' => 1
)
);
// Si hubo un error, lo logueamos
if ($result['error']) {
$errors[] = $email['user'];
}
}
// Reportamos si hubo errores
if (!empty($errors)) {
echo 'Errores al modificar los siguientes usuarios:';
echo implode($errors);
}
// Si no, retornamos un mensaje feliz
echo 'Finalizado!';
Tengan en cuenta que, si bien nuestro API es muy rápido, cada llamada HTTP toma su tiempo: la ejecución de PHP puede cortarse si superamos el tiempo máximo para un proceso (60 segundos).
Este ejemplo es ilustrativo, si tienen decenas y decenas de casillas de correo conviene hacer el proceso por partes. Para eso en todos los listados pueden utilizar paginado, definiendo:
offset, la posición en la que queremos que comience nuestro listadolimit, la cantidad de registros a obtener
Por ejemplo, para obtener la primer página de un listado largo podemos definir offset en 0 y limit en 20. Para obtener la segunda definimos offset en 20, para la tercera en 40 y así sucesivamente.
En resumen
Nuestro nuevo API REST maneja todas sus funciones de una forma similar, por lo que pueden consultar en nuestra documentación el resto de los módulos y ponerlos en práctica.
Por ejemplo, pueden agregar autorespuestas para un listado de usuarios de email, crear usuarios FTP temporales, cambiar el horario de ejecución de un cron, descargar backups… todo desde sus propias aplicaciones, utilizando nuestro API.
Si tienen alguna consulta, no duden en escribirnos a desarrollo@elserver.com para que podamos brindarle toda la ayuda que necesiten.