+54 11 5258-8400
Login

Archivo de la etiqueta: api

Accediendo a tus estadísticas desde el API

Una de las consultas más frecuentes es la de poder habilitar un usuario especial que tenga acceso solamente a la sección estadísticas. Implementar esto significaría, o bien crear un usuario específico para dicha sección, lo que es demasiado particular, o armar un sistema de ACL que haría la tarea de administrar usuarios y permisos bastante tediosa.

La buena noticia es que a través del API del nuevo panel y la versatilidad que ofrece se puede llevar a cabo en no más de 2 llamadas.

Como hablamos en posts anteriores, el nuevo panel dispone de un API REST que permite ejecutar absolutamente cualquier funcionalidad disponible para la nueva UI desde cualquier lugar. Si, esto quiere decir que si la nueva UI no es enteramente de su agrado y disponen del tiempo, pueden hacer la suya con las mismas exactas funciones. O en este caso, para algo más sencillo como resolver una necesidad puntual.

Ahora si, vamos al código

En primer lugar, lo que debemos hacer es acceder con nuestro SSO y nuestra clave

http://cloudapi.elserver.com/sso/login/?sso=usuario@dominio.com&password=mypassword

Una vez que hicimos esa llamada, obtendremos un access_token para autenticarnos en las futuras llamadas que realicemos.

Ahora bien, una vez que pudimos acceder y tenemos nuestro access_token, podemos ejecutar el pedido de estadísticas que debe ser un GET a /analytics/web/stat/

Eso es todo. Para que les resulte más fácil, les dejo a continuación un ejemplo en php de como se vería la versión final del código:

<?  /******** Begin Configuraciones *********/  $sso = ''; // SSO con el cual accederemos  $password = ''; // Clave del SSO  $account = ''; // Cuenta de la cual queremos obtener las estadisticas  $pointer = ''; // Dominio puntero del cual queremos las estadisticas (por defecto se completara el mismo que la cuenta)  /********* End Configuraciones **********/  $year = date("Y");  $month = date("m");  $pointer = ($pointer == '')? $account : $pointer;  // Me autentico al API  $auth = json_decode(file_get_contents("http://cloudapi.elserver.com/sso/login/?sso=$sso&password=$password"));  if ($auth->error)
    die($auth->error->message);
$access_token = $auth->access_token;

// Pido las estadisticas de la cuenta
$stats = file_get_contents("http://cloudapi.elserver.com/analytics/web/stat/?access_token=$access_token&account=$account&site=$pointer&year=$year&month=$month&type=report");
if (!$stats)
    die('No hay estadísticas para '.$pointer.' en el mes '.$month.' de '.$year);
die($stats);
?>

Para acceder a la documentación completa del API y toda la funcionalidad disponible, pueden acceder a http://www.elserver.com/comunidad/api/

Cómo utilizar el API de ELSERVER.COM: PHP en acción

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:

  • method indicará el método HTTP a utilizar: GET, POST, PUT o DELETE,
  • url será la URL del API con la que queremos contactar,
  • data será 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 listado
  • limit, 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.

Nuevo panel: Frontstage y Backstage de creación de usuarios de mail

Uno de los aspectos más potentes del nuevo panel de control es la posibilidad de ejecutar cualquier acción a través de nuestro API. Es una de las características fundamentales de nuestra nueva aplicación, al punto tal que la UI (es decir la interfaz del usuario) está desarrollada íntegramente en JavaScript y todo el procesamiento se realiza mediante llamadas al API. Esto quiere decir que cualquier usuario de la plataforma, o que simplemente tengan un usuario SSO, puede crear un Panel de Control con exactamente las mismas funcionalidades.

En este artículo vamos a tomar como ejemplo una acción cotidiana como dar de alta un usuario de mail y ver que es lo que pasa detrás de escena.

Alta de un usuario de mail desde el Panel de Control

Para crear un usuario de mail los pasos son los siguientes:

1- Ingresar al panel de control (http://panelbeta.elserver.com/) con tu SSO.

2- Seleccionar desde la izquierda la cuenta a la que le querés crear un nuevo usuario de mail.

3- Una vez desplegado el menu de la cuenta, hacer click en Emails.

4- En esta sección hacer click en el botón de “Agregar email”.

5- Completar los datos de Usuario y Contraseña del nuevo mail.

6- Hacer click en el botón de “Guardar Cambios”.

Alta de un usuario de mail mediante el API

Para replicar esta misma funcionalidad pero directamente desde el API del Panel de Control, debemos:

1- Validarnos: Para ejecutar cualquier comando en el API debemos tener un Access Token. Para obtenerlo, debemos ejecutar un login en el módulo SSO, que se traduce a lo siguiente:

http://cloudapi.elserver.com/sso/login/?sso=miusuariosso@dominio.com&password=miclavedesso

El resultado será un json con 2 datos: access_token y sso. Almacenemos el primero porque lo necesitaremos para todas las llamadas que hagamos al API.

2- Ejecutar el alta: A diferencia de la UI, el API recibe directamente la cuenta sobre la que vamos a trabajar como un parámetro, no hace falta ejecutar ninguna instrucción de selección de cuenta. El namespace del módulo es /account/email/ y siguiendo los lineamientos de cualquier API REST debemos hacer un POST a esa dirección para agregar un elemento nuevo.

Para cualquier acción que no sea GET, podemos usar cualquier aplicación online o para facilitar las cosas el API soporta que le sobreescriban el método con un argumento del estilo method=POST. Esto último es lo que usaremos en esta oportunidad.

Ya tenemos nuestro access_token, y el namespace y método a donde debemos enviar nuestra información, solo resta elegir nuestro usuario y clave: cosmefulanito@midominio.com y clave eseperrotienelacolapeluda en nuestra cuenta midominio.com. La llamada completa quedaría así:

http://cloudapi.elserver.com/account/email/?account=midominio.com&user=cosmefulanito@midominio.com&password=eseperrotienelacolapeluda&method=POST&access_token=[ACCESS_TOKEN]

Si todo salió correctamente, deberíamos obtener un json con una respuestas {data: 1}. y listo, acabamos de emular la funcionalidad del Panel de Control pero directamente en el API.

Espero que les sirva como introducción al uso de nuestro API. En los próximos días profundizaremos más en los módulos que lo componen y en su utilización.

Cómo utilizar el API de ELSERVER: primeros pasos

Si las palabras JSON RESTFul API no te suenan familiares, esta guía es para vos: hoy vamos a ver cómo utilizar el API de ELSERVER desde cero. ¡Comencemos!

¿Qué es un API?

Sin entrar en palabras complicadas, un API sirve para leer o modificar información de una web desde un sitio externo. Esto permite que cualquier desarrollador pueda integrar funcionalidad de cierto servicio web en sus propias aplicaciones.

Muchas plataformas ofrecen un API público para sus usuarios. Por ejemplo, con el API de Facebook podemos mostrar amigos, fotos y Likes; con el API de Twitter podemos publicar y leer tweets; con el de Flickr podemos obtener o subir fotos… y mucho más, en muchos más servicios.

Lo mejor es que casi la totalidad de los API disponibles son independientes del lenguaje de programación que usemos: desde Javascript, PHP, Phyton o cualquier otro lenguaje podremos utilizar las mismas funciones y obtener resultados idénticos.

Entonces, ¿qué permite hacer el API de ELSERVER? Literalmente todo: todas las tareas que podés realizar desde el Panel de Control, podés hacerlas a través de nuestro nuevo API.

Manos a la obra

Nuestro API es REST, es decir, utiliza los siguientes métodos HTTP:

  • GET para listar elementos
  • POST para crear un nuevo elemento
  • PUT para modificar un elemento
  • DELETE para eliminar un elemento

Las llamadas deben hacerse a una URL con la siguiente estructura:

http://cloudapi.elserver.com/

Donde method define el elemento en cuestión: email, site, admin, etc. En nuestra web se encuentra la lista completa de los módulos disponibles hasta el momento.

Cada llamada tiene una serie de parámetros a enviar. Dos de ellos son necesarios para casi todas las funciones:

  • account, el nombre de la cuenta donde se encuentra el elemento a leer o modificar
  • access_token, un código que identifica a nuestro usuario para que el API sepa que tenemos permiso para acceder a la cuenta deseada

Para obtener un access_token debemos validarnos, de la siguiente forma:

GET http://api.elserver.com/sso/login/
    ?sso=micuenta@ejemplo.com
    &password=miclave

… siendo los parámetros sso y password los mismos que utilizás para ingresar al Panel de Control. La respuesta a esta llamada será un JSON con este formato:

{
    "access_token": "0ed896b0dc2wb7cwwb748drbt7a9f8d6",
    "sso": "micuenta@ejemplo.com"
}

Esa maraña de letras y números es tu access_token. Es muy importante que no lo compartas, ya que es un código que te identifica como usuario: es como si fuera tu SSO y password, dos en uno.

Debemos enviar este parámetro en todas las llamadas porque es una forma simple de decirle al API quienes somos, que sepa que tenemos permiso para hacer lo que le pedimos.

Por ejemplo, listar las casillas de correo de una cuenta:

GET http://api.elserver.com/email/
    ?account=micuenta
    &access_token=0ed896b0dc2wb7cwwb748drbt7a9f8d6

Si enviamos los datos correctamente, recibiremos una respuesta como esta:

{
    "paging": {
        "records": 2
    },
    "data": [
        {
            "info": "Juan",
            "msgsize": 0,
            "hardquota": 0,
            "mailing": 0,
            "isalias": 0,
            "antispam": 1,
            "autoreply": 0,
            "user": "juan",
            "softquota": 0
        },
        {
            "info": "Esteban",
            "msgsize": 0,
            "hardquota": 0,
            "mailing": 0,
            "isalias": 0,
            "antispam": 0,
            "autoreply": 0,
            "user": "esteban",
            "softquota": 0
        }
    ]
}

Todos los listados tienen un formato idéntico: en paging obtendremos la cantidad total de registros, en data un array de los mismos con sus detalles particulares.

Por ejemplo, mirando el resultado que obtuvimos, podemos saber qué casillas de nuestra cuenta tienen activado el filtro antispam chequeando si ese parámetro está en 0 o 1.

Ya hemos visto en acción las operaciones de lectura, con las cuales obtenemos datos. Pasemos ahora a las de escritura: ¿cómo hacemos para modificar ese dato? ¿Y cómo creamos un usuario de correo nuevo? Bien, sigamos adelante.

Enviando datos al API

Para estas llamadas utilizaremos la misma URL pero con distintos métodos: POST, PUT y DELETE. Como siempre, son obligatorios los parámetros account y access_token, más los que requiera cada pedido.

Agregar

Por ejemplo, para crear una casilla de correo hacemos un POST agregando:

  • user, el nombre de la casilla a crear
  • password, la clave de la casilla a crear

Si todo salió bien, el API crea la casilla en el instante y ya podemos utilizarla, por ejemplo, ingresando a ella a través del nuevo Webmail.

Modificar

Para modificar una casilla de correo, enviamos un PUT con:

  • user, el nombre de la casilla a modificar

… y la clave de todas las propiedades que querramos modificar, con su nuevo valor.

Eliminar

Es muy simple, lo logramos con un DELETE especificando:

  • user, el nombre de la casilla a borrar

Como ven, el campo user funciona como el ID único en esta serie de elementos. En esto, nuestro API se diferencia de algunos otros que utilizan IDs numéricos incrementales que forman parte de la URL en los pedidos PUT y DELETE. Tengan en cuenta este detalle al utilizar los métodos sync de librerías Javascript como Backbone o Spine.

Mensajes de éxito o error

Si la operación fue exitosa, en la respuesta veremos este flag:

{
    "data": 1
}

En caso de error recibiremos un aviso como este:

{
    "error": {
        "type": "oError",
        "message": "Selected user does not exist"
    }
}

Emulando métodos HTTP

Algunos navegadores no permiten los métodos PUT o DELETE, por eso los formularios web siempre utilizan sólamente GET o POST. Para eludir esta limitación, podemos emular estos métodos especificando el parámetro opcional method. El API tratará a esa llamada como si de un método nativo se tratara:

GET http://api.elserver.com/email/
    ?account=micuenta
    &access_token=0ed896b0dc2wb7cwwb748drbt7a9f8d6
    &user=esteban
    &info=Test
    &method=PUT

Es decir que podemos ejecutar operaciones de cualquier tipo directamente desde la URL de nuestro navegador (un pedido GET) especificando el método deseado (POST, PUT o DELETE).

En resumen

Hoy vimos cómo hacer llamadas al API en general, a través de HTTP, pero sin aplicarlo puntualmente a ningún lenguaje de programación. En el próximo post vamos a ver cómo poner todo esto en acción desde PHP, creando una librería simple para manejar validaciones y pedidos.

Por ejemplo, podemos programar un script que cree usuarios FTP descartables para que nuestros clientes puedan enviarnos archivos pesados, comparar dos archivos de nuestros backups o procesar las estadísticas de las visitas a nuestra web para hacer nuestros propios gráficos. ¡Las posibilidades son enormes!

Mientras tanto, pueden probar el API online en nuestro playground. En los comentarios vamos a responder cualquier duda o consulta.

¡Hasta el próximo post!

Esto no es Diseño, es Diseño Web

¡Seguimos con las clases! En 2012 lanzamos nuestro programa exclusivo de capacitación en diseño y desarrollo web en la Universidad de Palermo y queremos que seas parte 😀

Ya pasó el primer módulo “Tomando la pastilla roja” donde te explicamos todo acerca del backstage de internet. Ahora ponemos el foco en el Diseño Web. ¿Por qué decimos que ESTO NO ES DISEÑO, ES DISEÑO WEB?

Porque no vamos a hablar de diseño gráfico simplemente sino que vamos a aprender cuáles son las herramientas necesarias que pueden usar los profesionales para aplicar sus capacidades de diseño en el mundo online sin sacrificar estética ni usabilidad. Revisaremos los principales lenguajes y trucos para que, sin ser programador, puedas comenzar a desarrollar sitios y aplicaciones de manera exitosa. Algunos de los temas que vamos a abordar:

– Introducción: HTML y CSS HTML: ¿Cómo se compone una página web? Sitios web estáticos y dinámicos. CSS: Estilo. Imágenes optimizadas para web.
– Diseño para web
CSS3: Ventajas y aplicaciones. Un diseño para muchos dispositivos: responsive design. Crossbrowsing. Maquetación. ¿Se puede programar un diseño? Perdiéndole el miedo al código fuente. Diseño desde el navegador.
– Diseño de aplicaciones
HTML5: Diseñando aplicaciones. Paradigmas actuales. Diferencias con sitios web clásicos. Javascript y jQuery: contenido dinámico, animaciones, AJAX. Social APIs: comunicando tu aplicación con Facebook, Twitter, Flickr y más.
– Diseño efectivo para campañas de email marketing
Newsletters: ese mundo aparte. Cómo hacer un diseño efectivo para los diferentes clientes de correo.
– Cómo relacionarse con el cliente desde el punto de vista del diseñador web.

Por ser cliente tenés un 20% de descuento en la cuota.

¡Empezamos en unos días, no te lo pierdas!

Carga Horaria total: 18 hs. (6 clases de 3 horas cada una) Miércoles (06, 13 y 27 de junio + 04, 11 y 18 de julio 2012) de 19 a 22 hs.

Arancel: $500.- Si sos cliente de ELSERVER.COM $400,- mencionando este correo

¡Inscribite por correo a marketing@elserver.com y obtené tu beneficio!
Mandanos tu nombre, apellido, dirección de correo electrónico y teléfono

LAYOUT

SAMPLE COLOR

Please read our documentation file to know how to change colors as you want

BACKGROUND COLOR

BACKGROUND TEXTURE