Gerar documentação da API automaticamente

[turicas]

Tudo o que precisamos para gerar automaticamente a documentação da API, por tabela, está no banco, nos models Dataset, Version, Table e Field. A documentação da API pode ser uma página dentro do próprio Brasil.IO, com uma descrição geral do dataset e um índice por tabela, bem parecida com a documentação (feita manualmente) do dataset covid19.

[endersonmaia]

Se formos partir para solução do datapackage como fonte primária, seguem alguns recursos para referência :

• https://github.com/frictionlessdata/datapackage-py
• https://specs.frictionlessdata.io/data-package/

[turicas]

Se o datapackage.json atender à demanda que temos hoje (já explico abaixo), então acho que o ideal seria termos apenas o datapackage.json no repositório, assim o Brasil.IO poderia consumir desse arquivo e os arquivos schema/*.csv poderiam ser gerados automaticamente a partir do datapackage.json (ou, quando a rows suportar pgimport e csv2sqlite com data package, eles poderiam ser deletados).

As demandas atualmente são:

• Especificação dos nomes e tipos das colunas (como já existe no schema/*.csv)
• Metadados gerais, como: nome da coluna (slug), título da coluna (com acentos, espaços etc.), descrição da coluna
• Metadados específicos para o Brasil.IO, como: quais colunas aparecerão como filtro na interface, quais colunas serão exibidas no frontend, quais colunas serão usadas para compor o índice de busca por texto completo etc. (esses eu escolho manualmente quando vou adicionar um dataset na plataforma)

Eu não conheço muito da especificação do data package, mas se tiver como embutirmos metadados personalizados (esses do Brasil.IO), então podemos começar um processo de migração (ficará bem melhor se for uniformizado assim :).

Sobre a geração de documentação da API: como os metadados precisam ficar armazenados na base do Brasil.IO (e não serão exatamente iguais a esse datapackage.json que propus, pois nem sempre o dataset estará super atualizado com relação ao repositório), então faz sentido a geração da documentação da API ser feita automaticamente a partir do banco de dados do Brasil.IO e não do (futuro) datapackage.json.

[augusto-herrmann]

O Data Package possibilita, sim, ter um esquema personalizado de metadados, usando a funcionalidade de Profiles.

Há dois tipos de perfis de metadados: o relativo ao "Package" (entenda-se como sendo o dataset) e relativo ao "Resource" (entenda como o arquivo, ou a tabela). Nesse caso, como a necessidade é de informações sobre as colunas / campos dos dados, entendo que o tipo de Profile que precisamos gerar é o do Resource.

Funciona assim: na parte do datapackage.json que se refere ao Resource, colocamos o atributo profile com o valor que aponta para uma URL que tem o JSON Schema que será usado para fazer a validação dos campos que queremos. Esse JSON Schema ainda tem que ser desenvolvido.

O problema é que, ao definir que o Resource tem um Profile personalizado, ele deixa de usar o Profile Tabular Data Resource. Com isso, as ferramentas de verificação como o Good Tables provavelmente não reconhecerão o padrão e não farão as verificações que nos interessam – como a validação de tipos de campos, valores aceitáveis, etc.

Essa é uma questão que vale a pena levar aos fóruns do Frictionless Data. Criei uma issue lá sobre isso.

Entendo que o mais importante é ter a validação funcionando pelas ferramentas. Se isso tornar viável a validação, talvez uma alternativa seja criar um Profile personalizado no nível de Package e colocar os metadados lá, deixando os Resources com o Profile tabular-data-resource mesmo.

Obs.: depois de criar o esquema do Brasil.io, ele poderá ser publicado no catálogo de esquemas do Frictionless Data, quando este existir. A ideia de ter um catálogo está sendo discutida nesta issue e explicada nesta postagem de blog.

[endersonmaia]

abrindo outro tópico aqui mas relacionado à API e tal

sei que tem uma issue sobre usar o PostgREST (#125), e recentemente brasil.io tá sofrendo com a sobrecarga devido à repercussão do dataset COVID19-BR

o que vc acha de uma reformulação na infra da API especificamente ?

poderia colocar o PostgREST pra rodar, e já fornece documentação de API via Swagger (OpenAPI), e dá uma aliviada no consumo de recursos do servidor

é preciso por à prova no cenário do Brasil.IO, eu já testei PostgREST e funciona muito bem e é bem leve

daí faria uma transição com um domínio como api.brasil.io, deixa ainda no django, e depois cria um path /v2 para migrar pro PostgREST

e no meio disso ver como encaixar o datapackage.json sendo gerado pelos dados do PostgREST

[augusto-herrmann]

Do meu ponto de vista, que não estou trabalhando na manutenção da API, essa me parece uma ótima ideia! Além disso, liberaria os esforços que hoje são despendidos em manter não só a documentação como também o código da API em si.

Bem observado que teria que deixar um tempo com ambas as APIs para uma transição, até que as pessoas que a consomem migrem para a nova API.