Un API de búsqueda en el CABYS

5 min readSep 4, 2020

Como implementar un API para buscar en el CABYS de Hacienda

Cuál es la idea?

Implementar un API con búsqueda difusa para buscar fácilmente términos en el Catálogo de Bienes y Servicios y poder conectarse al mismo desde una aplicación.

Stack usado

El documento no entra en detalles de qué son estas herramientas y cómo funcionan, si desea puede investigar usando los links de referencia.

Apache Solr, para las búsquedas (https://lucene.apache.org/solr/)
KrakenD, como API gateway (https://www.krakend.io/)
CABYS en formato Excel, como origen de los datos.
Una instancia en GCP, para hospedar todo. (https://console.cloud.google.com/compute/instances)

Instalación

Primero, el VPS.

Ahora, para configurar la instancia puede seguir los pasos en este link , con las siguientes aclaraciones.

Las instrucciones en el link son para configurar una instancia “gratis” en GCP, si ya cuenta con un VPS o servidor donde correr Solr, puede continuar al siguiente paso.

A pesar de que en el link vienen las instrucciones para una instancia F1-micro, la misma no es suficiente para soportar Solr. Una opción económica que soporte esta configuración es la siguiente:

Una vez configurado el VPS, procedemos a instalar Solr.

Debe abrir la consola SSH web para la VPS que acaba de configurar. La instancia puede tardar unos minutos en estar arriba.

Instalamos OpenJDK 11

sudo apt-get install openjdk-11-jre openjdk-11-jdk

Instalamos Apache Solr

wget https://downloads.apache.org/lucene/solr/8.6.2/solr-8.6.2.tgz;tar xzf solr-8.6.2.tgz solr-8.6.2/bin/install_solr_service.sh --strip-components=2;sudo ./install_solr_service.sh solr-8.6.2.tgz;

Apache Solr tiene una version web que corre en el puerto 8083 pero que no vamos a usar por ahora.

Configuración

Ahora necesitamos la fuente de datos, el CABYS

Descargue la versión completa en Excel del sitio oficial de Hacienda.

Catálogo de bienes y servicios

BCCR, Banco Central de Costa Rica, economia, política monetaria, política cambiaria, dinero, inflación, oferta…

www.bccr.fi.cr

Para poder usar los datos, edite la versión en Excel y haga los siguientes cambios:

Elimine la fila 1
Elimine la imagen del Ministerio de Hacienda
cambie los encabezados por nombres clave, en minúsculas, sin espacios, por ejemplo:

“Categoria 1” por “categoria1”, “Descripcion (categoria 1)” por “descripcion1”, “Impuesto” por “impuesto”

Debería verse similar a esta imagen:

Finalmente, exporte a un archivo CSV

Ahora hay que subir el CSV al servidor, si esta usando su propio servidor puede ignorar este paso.

Usando la consola SSH web de la VPS, seleccione “subir archivo” del menu en la consola.

Una vez subido el archivo CSV, volvemos con Solr

Debe crear una colección en Solr para este archivo

sudo su - solr -c "/opt/solr/bin/solr create -c cabys -n data_driven_schema_configs"

Una vez creada, debe importar el archivo CSV a la colección, usando:

/opt/solr/bin/post -c cabys cabys04092020.csv

Debe recibir un mensaje similar a este:

java -classpath /opt/solr/dist/solr-core-8.6.2.jar -Dauto=yes -Dc=cabys -Ddata=files org.apache.solr.util.SimplePostTool cabys04092020.csv
SimplePostTool version 5.0.0
Posting files to [base] url http://localhost:8983/solr/cabys/update...
Entering auto mode. File endings considered are xml,json,jsonl,csv,pdf,doc,docx,ppt,pptx,xls,xlsx,odt,odp,ods,ott,otp,ots,rtf,htm,html,txt,log
POSTing file cabys04092020.csv (text/csv) to [base]
1 files indexed.
COMMITting Solr index changes to http://localhost:8983/solr/cabys/update...
Time spent: 0:00:10.120

Ahora para consultar el CABYS puede usar el siguiente comando:

curl --request GET 'http://localhost:8983/solr/cabys/select?indent=on&q=descripcion:cosmetiquera~&wt=json&fl=codigo,descripcion,i
mpuesto'

Debe recibir un JSON de respuesta como el siguiente, el cual contiene todos los artículos del CABYS que contienen “cosmetiquera” como parte de su campo “descripcion”

{
  "responseHeader":{
    "status":0,
    "QTime":24,
    "params":{
      "q":"descripcion:cosmetiquera~",
      "indent":"on",
      "fl":"codigo,descripcion,impuesto",
      "wt":"json"}},
  "response":{"numFound":6,"start":0,"numFoundExact":true,"docs":[
      {
        "codigo":[2922006990100],
        "descripcion":["Estuche para maquillaje (cosmetiquera) y para artículos de baño (neceser), de otros materiales n.c.p."],
        "impuesto":["13%"]},
      {
        "codigo":[2922006990100],
        "descripcion":["Estuche para maquillaje (cosmetiquera) y para artículos de baño (neceser), de otros materiales n.c.p."],
        "impuesto":["13%"]},
      {
        "codigo":[2922006010100],
        "descripcion":["Estuche para maquillaje (cosmetiquera) y para artículos de baño (neceser), de cuero natural o regenerado"],
        "impuesto":["13%"]},
      {
        "codigo":[2922006020100],
        "descripcion":["Estuche para maquillaje (cosmetiquera) y para artículos de baño (neceser), de plástico o materiales textiles"],
        "impuesto":["13%"]},
      {
        "codigo":[2922006010100],
        "descripcion":["Estuche para maquillaje (cosmetiquera) y para artículos de baño (neceser), de cuero natural o regenerado"],
        "impuesto":["13%"]},
      {
        "codigo":[2922006020100],
        "descripcion":["Estuche para maquillaje (cosmetiquera) y para artículos de baño (neceser), de plástico o materiales textiles"],
        "impuesto":["13%"]}]
  }}

Ahora… exponemos el API

Para eso hay varias opciones:

Puede exponer directamente el puerto 8983 en donde se ejecuta Solr y consumir el API
Si esta trabajando en su mismo servidor, hay JDKs para Solr para conectar su aplicacion al servicio de búsqueda directamente
Puede exponer un API reducido en el puerto 80 del VPS y no el API completo de Solr, esto haremos a continuación usando KrakenD.

Configuramos el gateway

Para instalar KrakenD debe ejecutar en el VPS:

echo “deb http://repo.krakend.io/apt stable main” | sudo tee /etc/apt/sources.list.d/krakend.listsudo apt-get updatesudo apt-get install -y krakend --allow-unauthenticated

Ahora suba este archivo de configuración para el API al VPS. Si desea puede importar el mismo en el diseñador de KrakenD para ver detalles de la configuración.

La configuración hecha en este archivo expone un único endpoint en /cabys/{buscar} con el texto a buscar como parámetro y regresa el JSON desde Solr.

Despues de subir el archivo debe ejecutar:

sudo systemctl stop krakend;sudo cp 1599240117008-krakend.json /etc/krakend/krakend.json;sudo iptables -t nat -A PREROUTING -p tcp --dport 80 -j REDIRECT --to-port 8080;sudo systemctl start krakend;

Listo

Ahora el API puede consumirse desde el puerto 80, así:

http://104.196.102.103/cabys/texto-de-busqueda

Por ejemplo: http://104.196.102.103/cabys/cosmetiquera

La instancia de prueba usada en la elaboración de este documento está arriba y es funcional con ciertas restricciones y puede ser eliminada sin previo aviso. Si desea usar dicho API puede hacerlo pero considere que puede ser borrado en cualquier momento.