Agrega endpoints de descarga completa de datos.

Author: federicotdn

.travis.yml

@@ -6,8 +6,6 @@ install:
 - pip install -r requirements.txt -r requirements-dev.txt
 - sudo apt-get update -qq
 - sudo apt-get install -y openvpn
-env:
-- CFG_PATH=config/georef.example.cfg
 script:
 - make code_checks
 - make test_mock

Makefile

@@ -1,4 +1,9 @@
-CFG_PATH ?= config/georef.cfg
+# Makefile para georef-ar-api
+#
+# Contiene recetas para ejecutar tests, correr servidores de prueba
+# y generar la documentación.
+
+CFG_PATH ?= config/georef.example.cfg
 INDEX_NAME ?= all
 INDEXER_PY = service.management.indexer
 

config/georef.example.cfg

@@ -15,6 +15,40 @@ MAX_RESULT_LEN = 5000
 # a el valor index.max_result_window de Elasticsearch (default: 10000).
 MAX_RESULT_WINDOW = 10000
 
+# URLs de endpoints de descarga completa de datos Por ejemplo, el
+# usuario puede acceder a /api/departamentos.csv para descargarse la
+# base total de departamentos. Internamente la api realiza un HTTP
+# redirect a las URLs configuradas en COMPLETE_DOWNLOAD_URLS. En caso
+# establecer una URL como None, se desactivará el endpoint asociado.
+
+COMPLETE_DOWNLOAD_URLS = {
+    'provincias': {
+        'json': 'https://www.example.org',
+        'csv': None,
+        'geojson': None
+    },
+    'departamentos': {
+        'json': None,
+        'csv': None,
+        'geojson': None
+    },
+    'municipios': {
+        'json': None,
+        'csv': None,
+        'geojson': None
+    },
+    'localidades': {
+        'json': None,
+        'csv': None,
+        'geojson': None
+    },
+    'calles': {
+        # calles no tiene archivo geojson asociado
+        'json': None,
+        'csv': None
+    }
+}
+
 #------------------------------------------------------------
 # Configuración para indexación de datos
 #------------------------------------------------------------

service/__init__.py

@@ -11,5 +11,5 @@
 with app.app_context():
     # Crear parsers de parámetros utilizando configuración de Flask app
     import service.params
-
-import service.routes  # noqa: E402,F401 pylint: disable=wrong-import-position
+    # Crear rutas utilizando también configuración de Flask
+    import service.routes  # noqa: F401 pylint: disable=wrong-import-position

service/formatter.py

@@ -248,20 +248,28 @@ def create_param_error_response_bulk(errors):
     }), 400)
 
 
-def create_404_error_response(url_map):
+def create_404_error_response():
     """Retorna un error HTTP con código 404.
 
-    Args:
-        url_map (werkzeug.routing.Map): Mapa de URLs de la aplicación Flask.
-
     Returns:
         flask.Response: Respuesta HTTP con error 404.
 
     """
     errors = [
         {
             'mensaje': strings.NOT_FOUND,
-            'recursos_disponibles': list(str(r) for r in url_map.iter_rules())
+            # El listado de recursos podría utilizar app.url_map, pero es mejor
+            # listar los elementos más importantes manualmente para que la
+            # respuesta sea de mayor utilidad para el usuario.
+            'recursos_disponibles': [
+                '/api/provincias',
+                '/api/departamentos',
+                '/api/municipios',
+                '/api/localidades',
+                '/api/calles',
+                '/api/direcciones',
+                '/api/ubicacion'
+            ]
         }
     ]
 

service/routes.py

@@ -5,8 +5,9 @@
 """
 
 from functools import wraps
-from flask import request, Blueprint
+from flask import current_app, request, redirect, Blueprint
 from service import app, normalizer, formatter
+from service import names as N
 
 
 def disable_cache(f):
@@ -29,9 +30,39 @@ def decorated_func(*args, **kwargs):
     return decorated_func
 
 
+def add_complete_downloads(bp, urls):
+    """Agrega endpoints de descarga completa de datos a un Flask Blueprint.
+
+    Args:
+        bp (flask.Blueprint): Objeto donde agregar los endpoints de descarga.
+        urls (dict): Diccionario con tipos de entidades como claves, y
+            diccionarios como valores. Cada subdiccionario debe contener, por
+            cada formato (CSV, JSON, GEOJSON), una URL a donde redirigir (o
+            None para no agregar el endpoint). Ver el archivo
+            georef.example.cfg para más detalles.
+
+    """
+    entities = [N.STATES, N.DEPARTMENTS, N.MUNICIPALITIES, N.LOCALITIES,
+                N.STREETS]
+    formats = ['json', 'csv', 'geojson']
+
+    for entity in entities:
+        entity_urls = urls[entity]
+
+        for fmt in formats:
+            if entity_urls.get(fmt):
+                url = entity_urls[fmt]
+                # e.g: /provincias.csv
+                endpoint = '{}-{}'.format(entity, fmt)
+                rule = '/{}.{}'.format(entity, fmt)
+
+                bp.add_url_rule(rule, endpoint,
+                                lambda location=url: redirect(location))
+
+
 @app.errorhandler(404)
 def handle_404(_):
-    return formatter.create_404_error_response(app.url_map)
+    return formatter.create_404_error_response()
 
 
 @app.errorhandler(405)
@@ -42,6 +73,8 @@ def handle_405(_):
 # API v1.0
 bp_v1_0 = Blueprint('georef_v1.0', __name__)
 
+add_complete_downloads(bp_v1_0, current_app.config['COMPLETE_DOWNLOAD_URLS'])
+
 
 @bp_v1_0.route('/provincias', methods=['GET', 'POST'])
 def get_states():

tests/test_mock_routes.py

@@ -0,0 +1,40 @@
+import logging
+from unittest import TestCase
+from service import app
+
+
+logging.getLogger('georef').setLevel(logging.CRITICAL)
+
+
+class RoutesTest(TestCase):
+    def setUp(self):
+        app.testing = True
+        self.app = app.test_client()
+
+    def test_v1_0_endpoints(self):
+        """Los endpoints con prefijo /api/v1.0 deberían existir incluso si no
+        se cuenta con más de una versión de la API."""
+        urls = [
+            '/api/v1.0/provincias',
+            '/api/v1.0/departamentos',
+            '/api/v1.0/municipios',
+            '/api/v1.0/localidades',
+            '/api/v1.0/direcciones',
+            '/api/v1.0/ubicacion'
+        ]
+
+        validations = [
+            self.app.options(url).status_code == 200
+            for url in urls
+        ]
+
+        self.assertTrue(all(validations), list(zip(urls, validations)))
+
+    def test_complete_download_redirect(self):
+        """La API debería permitir la descarga total de datos por recurso. Las
+        descargas se implementan como una redirección a una URL donde se
+        almacenan los datos a descargarse (HTTP 302). La configuración de
+        ejemplo de la API utiliza una URL de ejemplo para /provincias.json."""
+        resp = self.app.get('/api/provincias.json')
+        self.assertTrue(resp.status_code == 302 and
+                        resp.headers['Location'] == 'https://www.example.org')