jueves, 26 de julio de 2012

Tutorial: comenzando a usar la API de ikiMap


Hace unos días presentábamos la API de ikiMap, mediante la cual proporcionamos una vía de integración con otros servicios y aplicaciones, siendo así posible acceder a ikiMap desde vuestros propios desarrollos: creando mapas, haciendo consultas, comentarios, votos, etc. A lo largo de una serie de artículos iremos explicando con ejemplos sencillos como utilizar la API.

La API de ikiMap se basa en una serie de servicios web REST simples, de modo que hay disponible un conjunto de métodos para las principales operaciones  que se pueden realizar con ikiMap.   A modo de ejemplo, para realizar una consulta utilizaríamos http://www.ikimap.com/api/search, para crear un mapa http://www.ikimap.com/api/createmap, para votar http://www.ikimap.com/api/vote, etc. 

La utilización de estos métodos web se podrá realizar mediante peticiones HTTP POST o HTTP GET, aunque este último no estará disponible para los métodos en los que sea necesario el envío de ficheros adjuntos a la petición. 

Así, la utilización de un método del API de ikiMap típica será:

http://www.ikimap.com/api/NOMBRE_SERVICIO?PARAMETROS 

proporcionándose en la petición una serie de parámetros, unos obligatorios y otros opcionales, para el método a utilizar.

En la documentación de la API encontrareis un listado detallado de estos métodos, indicándose para cada uno los parámetros obligatorios y opcionales, peticiones GET y POST, etc.  

Autenticación

Para poder utilizar la API de ikiMap necesitarás una clave de aplicación, que puedes solicitar en  este formulario.  Desde ikiMap se proporcionará un ID o clave de aplicación, así como un código secreto (token);  estos dos valores son imprescindible para la utilización de los métodos web, y no siendo posible obtener respuesta de ninguna petición que no proporcione estos valores.

Este ID de aplicación y código secreto se deberán incluir en todas las llamadas a la API de ikiMap en la forma de credenciales de autenticación HTTP básica, haciendo el ID de aplicación de  nombre de usuario y el código secreto de contraseña. 

Cualquier llamada a métodos de API que no incluya estas credenciales o que éstas sean incorrectas devolverán un código HTTP 401 (Unauthorized) y un mensaje de error “The application key and the secret code match with no apllication registered at ikiMap. Please, check again your acess data”.

Así, si ya dispones de una clave de aplicación podrás comenzar a realizar llamadas a métodos web del API de ikiMap. Puedes probarlo desde ya realizando peticiones desde un navegador web, utilizando URLs como por ejemplo:


 donde deberás incluir tu ID de aplicación y tu código secreto.

Ejemplo

Los lenguajes de programación y frameworks proporcionan mecanismos para realizar peticiones web con autenticación HTTP básica. Por ejemplo, utilizando PHP y la librería cURL podríamos hacer una petición con este código simple:
/* Método de API de ikiMap a utilizar, en este ejemplo es el método de búsqueda */

$url_metodo_api = "http://www.ikimap.com/api/search";

/* ID de aplicación y código secreto obtenidos de ikiMap */

$ID_aplicacion="ID_APLICACION";

$secret_code="CODIGO SECRETO";

/* Parámetros para utilizar con el método de búsqueda */

$params = array( "stringsearch"=>"ruta", "mode"=>"string");

/* Utilizamos la librería cURL */

$chBuscar = curl_init();

/* Configuramos URL del método para realizar la petición */

curl_setopt($chBuscar,CURLOPT_URL, $url_metodo_api);

curl_setopt($chBuscar, CURLOPT_RETURNTRANSFER, true);

/* Utilizamos HTTP POST */

curl_setopt($chBuscar, CURLOPT_POST, true);

/* Incluimos los parámetros del método de API */

curl_setopt($chBuscar, CURLOPT_POSTFIELDS, $params);

/* Se establece que se utilizará autenticación HTTP básica */

curl_setopt($chBuscar, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);

/* Se adjuntan las credenciales: ID de aplicación y código secreto */

curl_setopt($chBuscar, CURLOPT_USERPWD, "$ID_aplicacion:$secret_code");

/* Se realiza la petición y se obtiene la respuesta del método de API */

$response = curl_exec($chBuscar);

print $response; 
En el próximo artículo sobre el API de ikiMap hablaremos sobre el formato  de respuesta de los métodos de API de ikiMap y de cómo identificarse en las peticiones como un usuario registrado de ikiMap para realizar acciones como modificar los datos de perfil de usuario, acceder a mapas no públicos, etc, incluyendo algún ejemplo sencillo sobre el tema.

miércoles, 18 de julio de 2012

Presentando la API de ikiMap

Con el lanzamiento de la nueva versión de ikiMap, del que os hablamos hace unos días, también estrenamos nuestra API, como vía de integración con otros servicios y aplicaciones.

Toda la documentación de la API está accesible en esta dirección:


     ¿Qué puedo hacer con la API de ikiMap?

    La API de ikiMap tiene métodos  para interactuar con los mapas, ikiMapas, usuarios, hacer búsquedas y cometarios, realizar votaciones, etc. con lo que hay muchas posibles formas de usarla:
    • Crear una aplicación para móviles que visualice mapas de ikiMap.
    • Integrar tu aplicación de GPS para que la información la guarde en ikiMap y puedas consultar los tracks vía web.
    • Desarrollar un editor de mapas que almacene los datos en tu cuenta de ikiMap.
    • Crear widgets y extensiones para tus CMS preferidos.
    • ...

    ¿Cómo empiezo a usar la API?

    En próximos  artículos iremos publicando algunos sencillos ejemplos de como usar la API, pero para comenzar, puedes ir solicitando tu key de programador a través de este formulario.

    ¿Tiene algún coste?

     No, el uso de la API de ikiMap es gratuito, así que no tienes escusa para empezar a experimentar con ella :-)