• contacto

• euskara
• español
• english

Documentación de la API REST

Los objetivos de diseño principales de la API son:

• Utilización del estilo arquitectural REST.

• Diseño de una API limpia y agnóstica de su implementación. Actualmente al API está implementada en RubyOnRails pero podrá ser re-implementada o ampliada en el futuro en otras plataformas, como PHP o Zope.

• Uso de la librería OpenLayers para mostrar y trabajar con los mapas, lo que además permite que seamos directamente compatibles con Mapstraction.

• Utilizar el semi-estándar TMS para servir los mapas a OpenLayers

• Intentar adherirse a APIs estándares por todas la ventajas de interoperatividad que ofrecen.

• En un futuro posiblemente implementar los servicios de la Open Geospatial Consortium (OGC), que incluyen:

  • WMS.

  • WMS-C.

  • WFS.

En general, la API está dividida es dos partes:

• API para hacer consultas y obtener información.

• API para embeber y trabajar con mapas. Por embeber nos referimos a incrustar una ventana en la aplicación que un tercero está desarrollando.

Consideraciones generales

Esta API es accesible vía HTTP y sigue el estilo REST. El diseño de la API es agnóstico con respecto a una implementación particular, aunque tiene detalles de diseño de la implementación REST de RubyOnRails. Esta influencia de RubyOnRails está documentada en cada caso particular.

Tipo de coordenadas

A no ser que se indique lo contrario de forma explícita, todas las coordenadas (longitud/latitud) usadas en esta API están en la proyección Spherical Mercator con un SRS de "EPSG:900913".

URL base de la API

Todas las URLs que aparecen en este documento se aplican sobre la URL base del servidor donde se aloja la API. De momento esta URL base es:

b5m.gipuzkoa.eus/api/

Cabe destacar que una implementación en RubyOnRails es agnóstica del dominio utilizado ya que por defecto la aplicación web se auto-ajusta al dominio de la URL de petición.

Versionado

La API está versionada, de forma que pueda evolucionar sin interferir con los clientes que actualmente la utilicen. Los números de versión tienen la forma:

mayor.menor

Este documento describe la versión 1.0 de la API, por lo que la URL base será:

b5m.gipuzkoa.eus/api/1.0/

Una versión determinada de la API debe ser estable durante un tiempo prudencialmente largo para no interferir a los clientes actuales que la estén utilizando.

Localización

El resultado de muchas consultas contiene texto que debe aparecer localizado a petición del cliente.

La selección de la localización se hace de una forma RESTful, introduciendo un código de idioma en el path de la URL. Esto se hace en detrimento del uso de query strings (por ejemplo "?lang=es") tal como recomienda la RestBible (pags. 121-123).

Los códigos de idioma están especificados según el estándar ISO 639-1. Los códigos principales para nuestra aplicación son:

 - Euskera:    eu
 - Castellano: es
 - Inglés:     en
 - Francés:    fr

La especificación del código de lenguaje aparece después del número de versión de la API, como por ejemplo:

/api/1.0/es/

La parte "estructural" REST del path (cadena de directorios) de las URLs está en ingles y es independiente de la localización seleccionada. Esto es por consistencia, no tiene sentido que las URLs cambien según la localización seleccionada. Debido al estilo REST, hay partes del path que corresponden a parámetros de la consulta, y por tanto podrán estar localizados.

Los casos en los que los parámetros de consulta están localizados son para la "codificación" de entidades (municipios, calles...)

Por ejemplo, para obtener el MBR de un objeto (mas información en los detalles de la API)

/api/1.0/es/locate/mbr/M_069

La selección del locale se hace por medio la URL como se ha descrito, y de momento se ignora la cabecera HTTP Accept-Language. Esto es en concordancia con el estilo REST (RestBible 93,391).

En cualquier caso, todo el contenido textual devuelto por la API está codificado en UTF-8. De momento, la cabecera HTTP Accept-Charset será ignorada (RestBible 390).

Formato de salida

La API expone los recursos (datos) en diferentes representaciones. Típicamente estas representaciones incluyen los formatos:

• JSON
• XML
• TEXT (TXT,CSV)

La selección de la representación se realiza seleccionando de la siguiente lista el primer caso que se cumpla (estilo Rails):

1. Añadiendo una "extensión de formato" a la URL de la petición. Como por ejemplo:

   /api/1.0/es/locate/mbr/M_069.xml
   /api/1.0/es/locate/mbr/M_069.json
   

2. Utilizando la cabecera HTTP Content con el MIME type adecuado.

3. Si no se cumple ninguno de los casos anteriores, se devolverá en la representación por defecto que es XML.

No todos los recursos están disponible en todos los formatos. Los recursos exponen la lista de formatos en los que pueden ser obtenidos. La lista de formatos está accesible añadiendo la extensión ".formats" a la URL que prefija la "clase de recursos". Por ejemplo:

• /api/1.0/es/locate/mbr.formats
  /api/1.0/es/locate/info.formats
  

El resultado es una CSV textual con los formatos de representación soportados por esa clase de recursos.

EPSG

El API permite recibir los resultados en los sistemas de referencia: EPSG:900913 (Spherical Mercator -- por defecto), EPSG:4326 (WGS84) y EPSG:25830 (ETRS89). La selección del sistema de referencia se realiza mediante el parámetro srs.

/api/1.0/es/locate/mbr/M_069.xml;srs=epsg:25830
/api/1.0/es/locate/mbr/M_069.xml;srs=epsg:4326
/api/1.0/es/locate/mbr/M_069.xml;srs=epsg:900913

Formato JSONP

La API puede devolver los datos en formato JSONP. Este es un caso particular ya que hay que especificar cual es la función de callback.

Comúnmente se suele especificar este callback utilizando un query string en la URL. En nuestro caso podría ser algo como:

/api/1.0/es/locate/mbr/M_069.jsonp?callback=mi_funcion

Esta forma de especificar el callback no sigue el estilo arquitectural REST y no es caché friendly. Por ello se ha elegido una forma más REST de especificar el callback.

El callback se especifica utilizando un parameter (que no query string) en la URL:

/api/1.0/es/locate/mbr/M_069.jsonp;callback=mi_funcion

El parámetro callback puede estar URL-codificado. En el caso de utilizar un "." en el callback también hay que URL-codificarlo aunque no sea habitual. De hecho se recomienda URL-codificar todos los caracteres a excepción de letras y dígitos:

/api/1.0/es/locate/mbr/M_069.jsonp;callback=form%5B0%5D%2Efuncion   # equivale al callback "form[0].funcion"

Algunos ejemplos de peticiones:

Petición:

/api/1.0/es/locate/info/D_4545.json

Resultado:

{
    "info": {
        "type": "postal_id",
        "postal_code": {
            "id_municipality": "017",
            "name": "SALESIANOS, CONVENTO",
            "bis": " ",
            "postal_code": "20720",
            "district_code": "02",
            "municipality": "AZKOITIA",
            "num": "012",
            "street": "AIZKIBEL KALEA",
            "section_code": "002",
            "id_street": "1240"
        }
    }
}

Petición:

/api/1.0/es/locate/info/D_4545.jsonp;callback=funcion

Resultado:

funcion({
    "info": {
        "type": "postal_id",
        "postal_code": {
            "id_municipality": "017",
            "name": "SALESIANOS, CONVENTO",
            "bis": " ",
            "postal_code": "20720",
            "district_code": "02",
            "municipality": "AZKOITIA",
            "num": "012",
            "street": "AIZKIBEL KALEA",
            "section_code": "002",
            "id_street": "1240"
        }
    }
})

Petición:

/api/1.0/es/locate/info/D_4545.jsonp;callback=form%5B0%5D%2Efuncion

Resultado:

form[0].funcion({
    "info": {
        "type": "postal_id",
        "postal_code": {
            "id_municipality": "017",
            "name": "SALESIANOS, CONVENTO",
            "bis": " ",
            "postal_code": "20720",
            "district_code": "02",
            "municipality": "AZKOITIA",
            "num": "012",
            "street": "AIZKIBEL KALEA",
            "section_code": "002",
            "id_street": "1240"
        }
    }
})

Organización jerárquica de la API (''namespaces'' o espacios de nombres)

Las URLs de la API están estructuradas de forma jerárquica. En un primer nivel, se distingue el tipo de recurso a acceder por medio de un identificador:

Posteriormente, la URL sigue identificando los recursos de una forma jerárquica, desde el recurso que "engloba" a los demás hacia el recurso "más pequeño".

Operaciones REST de modificación

La versión actual de la API sólo soporta el método GET de HTTP, esto es, sólo permite obtener datos. Los métodos PUT, POST y DELETE no están soportados actualmente.

Seguridad y control de uso

La versión actual de la API no soporta ningún sistema de autentificación (API key). Todos los accesos son anónimos y no limitados.

Resumen de la estructura de las URLs

Definición de la API

Las URLs de estas definiciones son relativas al prefijo de su URL correspondiente.

Namespace "configuration/"

Estas URLs devuelven datos de configuración.

Se pueden ver ejemplos de su uso en: "ejemplos del namespace configuration".

Namespace "locate/"

Todas estas URLs devuelven datos y hacen referencia a objetos.

Los Objetos permitidos son los siguientes:

El formato de la respuesta de la búsqueda para search/:

Se pueden ver ejemplos de su uso en: "ejemplos del namespace locate".

Namespace "query/"

Estas URLs permiten obtener información sobre los objetos que están alrededor de una coordenada.

(*) Dada una coordenada y una lista de tipos de objetos geográficos a consultar devuelve una lista de objetos geográficos en cuya superficie está contenida la coordenada ("objetos que hay en ese punto"). Sólo se comprueban los tipos de objetos geográficos especificados, así que nunca se devolverá un objeto geográfico de un tipo no especificado. Parámetros:

lat: latitud
lon: longitud
tolerance: radio en KMs que define un area alrededor del punto en la cual se buscan los objetos (0 para buscar exactamente en el punto dado)
codes: lista de tipos de objetos geográficos separados por coma ("T,D,E") o asterisco ("*") para comprobar todos los códigos disponibles 

Namespace "layer/"

Estas URLs devuelven información asociada a una capa (ya sea ortofoto o mapa).

Se pueden ver ejemplos de su uso en: "ejemplos del namespace layer".

Namespace "pictometry/"

Estas URLs devuelven información sobre las imágenes de pictometry,

Se pueden ver ejemplos de su uso en: "ejemplos del namespace pictometry".

Namespace "library/"

Estas URLs permiten la carga de la librerías Javascript por parte del cliente. La librería base es "openlayers" pero en todos los ejemplos (y productos) vamos a utilizar las librerías "prototype" y "scriptaculous", así que (de momento) también las ponemos a disposición de los clientes.

Utilizamos un prefijo con el nombre de la librería para simplificar el rutado, ya que, por ejemplo, dentro de openlayers/ va a haber más directorios "ocultos" con resources que necesita OpenLayers (img/, css/ ...).

Los clientes pueden optar a cargar estas librerías desde otros sitios.

Se pueden ver ejemplos de su uso en: "ejemplos del namespace library".

Namespace "osgeo/"

Estas URLs son para acceder a "estándares" definidos por la OSGEO, de momento sólo para TMS.

Cartografías disponibles:

Se pueden ver ejemplos de su uso en :"ejemplos del namespace osgeo".

Aplicación de ejemplo

Se puede ver una simple aplicación haciendo uso de esta API en: "aplicación de ejemplo".