[Sugestão] Tornar as URL's do recurso "/referencias" mais Restful

[hbobenicio]

Motivação

As URL's do recurso /referencias/ da API REST, ao contrário das URL's dos demais recursos, utilizam convenções de nome fora do comum (quanto a sensibilidade de caixa e ao aninhamento de recursos). Por exemplo:

• Utilizam o padrão de caixa "lowerCamelCase", (não muito comum em rotas Restful), ao invés de convenções totalmente em minúsculo (vide item 5 deste link de convenções Rest), como o spinnal-case (aka kebab-case).
• Não consideram aninhamento de recursos (ao contrário das demais URL's da API)

Exemplos

Hoje: /referencias/situacoesDeputado ("As possíveis situações de exercício parlamentar de um deputado") /referencias/situacoesEvento ("As possíveis situações para eventos")

Poderia ser, por exemplo: /referencias/situacoes-deputado /referencias/situacoes-evento

Ou mesmo: /referencias/situacoes/deputado ou /referencias/deputados/situacoes /referencias/situacoes/evento ou /referencias/deputados/situacoes

Outro exemplo:

Hoje: /referencias/tiposEvento ("Os tipos de eventos realizados na Câmara") /referencias/tiposOrgao ("Os tipos de órgãos que existem na Câmara")

Poderia ser, por exemplo: /referencias/tipos-eventos /referencias/tipos-orgao

Ou mesmo: /referencias/tipos/eventos (ou /referencias/eventos/tipos) /referencias/tipos/orgaos (ou /referencias/orgaos/tipos)

[EquipeDadosAbertosCD]

Olá, Benício!

Obrigado pela sugestão e desculpe por não ter respondido antes. Eu podia jurar que já tinha respondido. Muita coisa na cabeça nos últimos meses... Perdão.

Eu já tinha essa mesma sensação sobre uma certa inconsistência do ramo /referencias e há algum tempo já foi especificada a alteração deles para um padrão bem próximo ao que você sugeriu. Está em homologação no momento e deve ser publicada já na próxima atualização da API. Por exemplo:

• /referencias/tiposOrgao vai passar a ser /referencias/orgaos/tipoOrgao
• /referencias/situacoesOrgao vai passar a ser /referencias/orgaos/situacaoOrgao
• Em /referencias/orgaos, você poderá obter os valores para tipoOrgao e situacaoOrgao em uma só resposta.

E o padrão segue para os demais endpoints do grupo.

Como você vê, só não vamos mexer na questão lowerCamelCase X _snakecase X kebab-case . Foi uma opção deliberada de design: JSON passou a ser o formato de dados prioritário da API; JSON é derivado de Javascript e na linguagem a prática é usar lowerCamelCase; e em prol da coerência e uniformidade da interface nós resolvemos manter esse padrão entre os elementos das estruturas de dados, os nomes de endpoints e os nomes dos parâmetros.

Mais uma vez, muito obrigado pela disposição em colaborar! Continue em contato! Abraço!

Fabricio Rocha Equipe Dados Abertos - Câmara