+54 11 5258-8400
Login

Cómo utilizar el API de ELSERVER: primeros pasos

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!

Related Post
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 […]

Read more
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 […]

Read more
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 […]

Read more
Post has 3 comments
  • Roberto O. Fernández Crisial Posted 13 mayo, 2013 in 2:11 pm

    Hola, como están?

    Les quería dejar una inquietud: para obtener el “access_token” un GET parece algo medio inseguro (mas para conexiones a través de proxies), el metodo puede ser reemplazado por POST?

    PD. Por lo que pude verificar, la API puede trabajar bajo SSL. Sería recomendable brindar los ejemplos con “https”.

    Saludos!

  • Dev Team Posted 13 mayo, 2013 in 3:57 pm

    Tito, ¡gracias por tu comentario! Sí, tenemos en vista cambiar a SSL tanto la documentación como la aplicación en cuanto terminemos de ajustar los detalles, incrementando así la seguridad de todas las llamadas al API. ¡Saludos!

  • Pingback: Cómo utilizar el API de ELSERVER.COM: PHP en acción | Juan Luis Mancilla E. info.Blogger

Deja un comentario

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *

LAYOUT

SAMPLE COLOR

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

BACKGROUND COLOR

BACKGROUND TEXTURE