jrub/feedbackAPIsAytoZgz.md

## feedbackAPIsAytoZgz.md

      
    Raw
  

              feedbackAPIsAytoZgz.md
            
          
    Feedback APIs Ayto Zgz

Web municipal

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)

API SOLR


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

Común a todas las APIs


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/

Ejemplos de datos mal estructurados en las APIs


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"},
  ],
  ...
}