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!

Compartí este artículo

3 Comentarios

  1. Roberto O. Fernández Crisial – 13 may 2013 (14:11:43)

    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 – 13 may 2013 (15:57:03)

      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!

Dejá un comentario

 

Ingreso Clientes

Datos incorrectos. Por favor revisa el e-mail y la contraseña.

Ingresaste correctamente.

Olvidé mi contraseña

Cerrar

Recuperar contraseña

Te llegará un correo con la información acerca de como proceder.

Volver

Cerrar