http://www.zaragoza.es/ciudad/actividades/
- Bug en la web: das a Próximos 7 dias. En la siguiente ventana, das a la pestaña "todo", y no cambia total de eventos, se queda fijo en 7 dias aunque cambia la pestaña (ver URL, concatena el parámetro "rango" sin más)
- en la web, sale todo ordenado por lastModified, por tanto una correción o modificación del evento hace que suba el evento arriba. No tiene mucho sentido. Yo si tuviera permisos de acceso para crear eventos, lo haría continuamente para promocionar mi evento al primero de la lista en mi categoría.
- Tras entrar a la sección "Fiestas Locales", aparece una nueva sección: JUVENIL
- Cambiar el título de http://www.zaragoza.es/docs-api/ (Swagger UI) a algo más atractivo
- En https://www.zaragoza.es/ciudad/risp/index_Api el literal "comporta sus datos" (en vez de Comparta)
- Cifrado de la web obsoleto e inseguro. Ver mensaje de Google Chrome al clicar el candado en (https://www.zaragoza.es/ciudad/risp/buscar_Aplicacion):
Your connection to www.zaragoza.es is encrypted with obsolete cryptography. However, this page includes other resources which are not secure. These resources can be viewed by others while in transit, and can be modified by an attacker to change the behavior of the page.
The connection uses TLS 1.0.
The connection is encrypted using AES_256_CBC, with SHA1 for message authentication and RSA as the key exchange mechanism.
- La web carga scripts no seguros, según Chrome (ver https://www.zaragoza.es/ciudad/risp/buscar_Aplicacion)
- SOLR devuelve ID con acto-id, y en el API REST eso corresponde a id (sin acto)
- fechaInicio_dt (pidiendo día 07, sale 06, por ser GMT): "2015-03-06T23:00:00Z", (es GMT)
- documentar que hay que pasar "rows" para que devuelva el total del numCount en vez de un rows=10 que devuelve por defecto
- descripcion_t suele contener la información de lugar_t, pero no siempre (homogeneizar tanto en solr como con las otras apis)
- El tema de las consultas FIQL es interesante pero el RFC no pasó a estándar y está obsoleto en 2008. Siete años depués... ¿igual es el momento de buscar alternativas mejores? :-D
### API REST
- documentar los endpoints de "tema" y "subtema"
- tema de devolver "S/N" frente booleanos: no vivimos en los 70
- en las peticiones a georref Latitud y Longitud están al revés, por ejemplo: http://www.zaragoza.es/georref/json/hilo/ver_Wifi?srsname=wgs84 …
- Para ponerlas en el orden correcto hay que añadir el parametro georss_valid http://www.zaragoza.es/georref/json/hilo/ver_Wifi?srsname=wgs84&georss_valid=s …
- la x y la y de lugar no están en wgs84, están en utm30 (pese a pedir wgs84)
### API SPARQL
- ¿se puede hacer que devuelva los objetos como el API SOLR en cuanto a no tener que acceder a "title.value"? (y englobado las dos apis en el mismo objeto, sea "bindings" -sparql- o "docs" -solr). Es decir, dar coherencia a las dos APIs para que devuelvan exactamente la misma estructura JSON.
- listado de los prefijos (PREFIX) cargados por defecto, no está documentado
- se devuelve contenido formateado en HTML en muchos campos. Es "de mala educación" ;-) y además no hay nada que identifique qué campo va a devolver texto o HTML, lo cual es peor todavía.
- Para que las APIs sean útiles para los reutilizadores, tienen que ser coherentes entre ellas (compartir todos los nombres de parámetros que devuelven, por ejemplo, y su contenido obviamente)
- No puede haber peticiones sin documentar (lista de temas/subtemas en el API Rest, por ejemplo). Si todas las APIs funcionaran "como uno espera", esto sería menos grave... pero el hecho de que han ido evolucionando a ritmos diferentes, cubriendo necesidades diferentes, y el hecho de enfocarse a cubrir la necesidad de una web de dos décadas, aún se nota a la hora de usarlas. Por eso destaco el, al menos, que haya coherencia entre ellas y que estén bien documentadas. Van por buen camino, pero tal cual están ahora hay casos en los que no se diferencia mucho de "minar datos a mano", porque el reutilizador tiene que ir descifrando el funcionamiento del API.
- Con el tema de cambiar APIs y por tanto "joder" a reutilizadores que ya las estén usando... quizás haya que empezar a implementar VERSIONADO de APIs... Aquí por ejemplo hay un articulillo, aunque ya viejo (2011) de Mark Nottingham, miembro del W3C (el que redactó el RFC del lenguaje de consultas FIQL que usáis en el API SOLR) https://www.mnot.net/blog/2011/10/25/web_api_versioning_smackdown O por ejemplo, cómo documenta Github los cambios de su API https://developer.github.com/v3/versions/
- Me repito una vez más: devolver HTML NO ES REUTILIZABLE. Sirve si te vas a hacer una web, no si quieres publicar un API. Un API sólamente debe contener datos estructurados, NUNCA JAMÁS texto libre.
- El gobierno de UK está haciendo un gran trabajo con el Open Data, podemos aprender de ellos:
- https://www.gov.uk/service-manual/technology/open-data.html
- Aquí, explican como HTML puede ser un formato adecuado para "written reports" (nunca .doc), pero para datos estructurados, siempre un formato como JSON o al menos XML: https://www.gov.uk/service-manual/user-centred-design/choosing-appropriate-formats
- Esto:
"price": "Entrada gratuita"
no sirve para nada a un reutilizador. ¿Y si lo queremos internacionalizar y mostrar en otro idioma? ¿Y si no queremos pintar ese texto sino una representación gráfica del dato? - Esto también es un error:
"datos": "<a href=\"http://www.zaragoza.es/pgou/edih/sanagustinplazaconvento.pdf\" class=\"pdf\">Interés
Un link no es un dato estructurado. Una URI sí lo es. Si se obliga al reutilizador a saber que ahí viene un elemento HTML (un href), entonces ya tiene que parsearlo, y ya no hay casi diferencia con hacer a mano un scraper y minar los datos con pico y pala. - Otro ejemplo:
"horario": "Cerrado hasta nuevo aviso.\r\n\r\nMartes a sábado de 10 a 14h y 17 a 21h
Imagina que no quiero mostrarlo, sino poner un botón que se integra con Google Calendar (o .ical en general) y al clicarlo añada ese evento al calendario del usuario. Efectivamente, al devolver un texto libre, un dato no estructurado, no sirve. Un ejemplo de cómo podría ser útil para los reutilizadores:
"horary": {
"monday": [
{"from": "08:00", "to": "17:00"},
],
"tuesday": [
{"from": "08:00", "to": "17:00"},
],
...
}
Lo que comento en efecto es un comentario general, no por una necesidad particular. No estoy pensando en ninguna app en concreto. Hablo en general de cómo deberían servirse los datos.
Una idea: probablemente el cómo devolvéis los datos depende de cómo los introducís en las bases de datos. Para el ejemplo que he puesto de precios el usuario que introduce los datos no puede tener un campo de texto libre, tendría que tener un formulario donde pueda introducir las diferentes tarifas, por ejemplo.
Sobre el versionado de APIs, es una cosa a tener en cuenta, pero si lo que se hace es añadir campos a la respuesta, no se rompe la compatibilidad hacia atrás. Si hay un campo
precio
no pasa nada por mantenerlo y añadir un campotarifas
(por ejemplo) con los datos estructurados y queprecio
continúe siendo un campo de texto libre.Otra cosa, además de que la información esté bien estructurada hoy en día las apps tienen que ser también atractivas. Idea: más contenidos multimedia en diferentes tamaños y resoluciones. Por ejemplo a la hora de devolver imágenes en vez de
"image": ..../.jpg"
propondría:Esto me permite elegir la mejor imagen para mi app y hacerla más vistosa. He puesto además de los tamaños en píxeles y sus urls un nombre a cada imagen porque esto me permite elegir el tamaño fácilmente. Y si quiero hilar muy fino puedo atender al
width
yheight
ignorando el nombre. Pero vamos, son ejemplos. Una imagen enlandscape
sería ideal para una cabecera de una web por ejemplo. Unthumbnail
debería ser cuadrado y sería ideal para un listado, etc. Esto que puede parecer complicado es relativamente fácil de hacer con unos comandos usandographicsmagick
sobre la misma imagen y no añade mucho trabajo para vosotros si tenéis alguna imagen grande original y luego se escala en diferentes tamaños. Y sin embargo para un "reutilizador" esto puede ser un salto cualitativo importante.Saludos,