geoapi.pt
geoapi.pt copied to clipboard
jfoclpf
Lidar com os caminhos `/municipios/` e `/municipios/base`
Isto se calhar devia ser um issue separado, mas o output HTML em https://geoapi.pt/municipios/ não devia ser igual ao de https://geoapi.pt/distritos/base, isto é, sem links? é que no JSON também aparecem links. Se entendi bem, para a API ser RESTFUL temos de garantir uma interface uniforme, e não personalizar o output de acordo com o formato de saída.
Originally posted by @waldyrious in https://github.com/jfoclpf/geoapi.pt/issues/92#issuecomment-1629727578
podes explicar melhor @waldyrious
- https://geoapi.pt/municipios/?json=1
- https://geoapi.pt/municipios
dá uma simples lista de municípios
não podemos mudar de forma a que fique backward incompatible, isto está em produção e é usado por muitas apps em produção
Mas o que é usado pelas apps é o JSON, não o HTML, certo? Não proponho mudar o JSON. O que quero dizer é que o output em HTML não devia ter links, porque isso é inconsistente com o que o output JSON dá.
Por exemplo, para os distritos, o resultado em HTML e JSON já é equivalente:
- https://geoapi.pt/distritos/base?json=1
- https://geoapi.pt/distritos/base
Tanto quanto entendo (e atenção, posso estar errado!), para respeitarmos os conceitos de uma API RESTful, o output deve ser uniforme (identificado apenas pelo URI), independentemente do formato ser JSON ou HTML ou outra coisa, apenas com ajustes derivados das limitações do próprio formato — por exemplo, em HTML o browser consegue mostrar imagens inline, enquanto que no JSON apareceria apenas o URL da imagem (o atribututo src do elemento <img), que o consumidor teria de descarregar.
Ou seja, os dados apresentados no output HTML deviam ser idênticos aos do JSON correspondente para todos os endpoints (não apenas este dos municípios). Possivelmente com recurso a <details> para não ser muito verboso em HTML.
Por exemplo, o JSON obtido de https://geoapi.pt/distritos/?json=1 tem os campos codigoine, geojson, censos2011 e censos2021, mas o HTML correspondente neste momento não mostra nada disso; e na direção oposta, o JSON devia ter links JSON+HAL para https://geoapi.pt/distrito/aveiro, etc. (tal como está no HTML).
Tanto quanto entendo (e atenção, posso estar errado!), para respeitarmos os conceitos de uma API RESTful, o output deve ser uniforme (identificado apenas pelo URI), independentemente do formato ser JSON ou HTML
Boas @waldyrious segundo sei não há nada no RESTful API que indique que HTML e JSON têm que ser coerentes entre si, na realidade a resposta HTML é tão incoerente e "caótica" (mapa, divs, cabeçalhos, footer, estilos CSS, título, etc.) que nem faz sequer parte da API (nenhuma aplicação decente usa html numa API, pois é difícil extrair informação).
O HTML foi apenas uma forma "bonita" e "user friendly" de mostrar o conteúdo dos caminhos, mas sem qualquer rigidez. No meu entender pouco importa se tem links ou não em HTML, embora os links sejam desejáveis para motores de busca (cross-linking).
Mas concordo contigo que o conteúdo deve ser coerente entre JSON e HTML, mas os links são irrelevantes, na minha opinião.
Por exemplo, o JSON obtido de https://geoapi.pt/distritos/?json=1 tem os campos
codigoine,geojson,censos2011ecensos2021, mas o HTML correspondente neste momento não mostra nada disso; e na direção oposta, o JSON devia ter links JSON+HAL para https://geoapi.pt/distrito/aveiro, etc. (tal como está no HTML).
o mapeamento não tem de ser exacto, porque o HTML não faz parte da API, é apenas uma forma "bonita" e "user friendly" de mostrar o conteúdo dos caminhos, além disso os censos aparecem quando fazes hover no mapa.
Abraços :)
Sim, não é obrigatório que o output HTML e JSON sejam compatíveis, mas não se torna confuso ter todos os endpoints da API a retornar conteúdo HTML quando acedidos a partir de um browser, e em certos casos corresponderem ao output em JSON, e noutros apenas parcialmente?
É que se forem consistentes, o site até acaba por servir como uma interface interativa para a API, permitindo as pessoas a explorar a funcionalidade e a criar um modelo mental do tipo de dados que podem ser obtidos, e como.
Em contrapartida, como está agora, pode induzir em erro — em certos casos "what you see (in HTML) is what you get (in JSON)", e noutros isso não acontece; e não é de todo evidente qual é a lógica que determina em que casos a usa-se a primeira abordagem e em que casos a segunda (se houver um padrão que me esteja a escapar, sou todo ouvidos! :smiley:)
concordo contigo que o conteúdo deve ser coerente entre JSON e HTML, mas os links são irrelevantes, na minha opinião.
Sendo assim, não seria caso para fechar o #55? Ou percebi mal o que queres dizer?
Mas eu concordo contigo que o HTML deva corresponder ao JSON para que seja uma interface à API (embora tenhas também o json=belo, ex: https://geoapi.pt/distrito/aveiro?json=belo), o que digo é que pouco importa os links nessa comparação. A correspondência deve ser apenas no "core" informativo.
Essa discrepância nos links está em todo o lado, exemplo:
- https://geoapi.pt/municipio/aveiro/freguesias
- https://geoapi.pt/municipio/aveiro/freguesias?json=1
Em princípio todo o HTML deveria vir com links, por motivos de SEO (cross-linking), assim como #55 faz sentido porque vai providenciar os links na resposta JSON.
Neste momento nenhum JSON vem com links e quase todos os HTML providenciam links
Sim, entendo. Concordo que o ideal seria progressivamente acrescentar links aos JSON (#55), e não remover os links. Infelizmente há casos em que não é possível fazê-lo sem partir a compatibilidade da API, e o endpoint municipios é um desses (porque a resposta é um array simples e portanto não podem ser acrescentados outros campos). Mas onde for possível, ya acho que avançar com os links no JSON, como descrito no issue #55, seria desejável.
Voltando ao tema original deste issue: Independentemente do output do JSON entre /municipios e /distritos/base (que é consistente, ou seja um array plano), acho que o HTML também devia ser equivalente, já que fazer isso não envolve quebrar a API.
Ou seja, para resolver este issue em particular, eu diria que o que falta fazer é acrescentar links no HTML em https://geoapi.pt/distritos/base, tal como são acrescentados em https://geoapi.pt/municipios. Isso faz com que o HTML não seja equivalente ao JSON nesses endpoints, mas como dizes, essa equivalência HTML←→JSON não é um objetivo do projeto, e pelo menos torna o HTML mais útil/prático.
para resolver este issue em particular, eu diria que o que falta fazer é acrescentar links no HTML em https://geoapi.pt/distritos/base,
fá-lo-ei ASAP