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.
