Produto GT4 - Publicação das diretrizes para estabelecimento de URIs

Modified on 21/11/2016 09:52 by Augusto Herrmann — Categorized as: GT4, Produto

Esta página está arquivada. Seu conteúdo não é atual e ela é mantida apenas para consulta de informações históricas.

Documento visando orientar a criação e manutenção de identificadores únicos dos recursos informacionais da INDA.

Descrição do produto


Desenvolvimento das atividades

As atividades estão em processo de iniciação, na fase de análise de diretrizes internacionais. Essa análise é insumo para a decisão de criação de novas diretrizes ou adoção das já existentes.

Tópicos ainda não tratados


Tópicos tratados


Documentos


Cronograma

Produto / AtividadeResponsávelStatusPrazo
Avaliar o documento Designing URI sets for the UK public sectorMarcos Fernandesconcluído16/06/2011

Comentários sobre coisas desejáveis



3. Deixar claro a terminologia utilizada, referenciar o IETF RFC 2616, a especificação do HTTP 1.1.

4. Deixar claro na documentação que o slug "[versao]" refere-se à versão da API, e não à versão do recurso identificado.

5. Seguindo a boa prática da comunidade Linked Data, descrita em vários livros e documentos do W3C, e amplamente praticada, é importante separar as URIs que identificam recursos não-informacionais (objetos, conceitos abstratos) das URIs que identificam recursos informacionais (documentos que podem ser transmitidos digitalmente). Estas utilizarão valor “doc” para o slug {natureza-recurso} e aquelas o valor “id”. As URIs do primeiro tipo deverão sempre retornar o código HTTP 303 (See Other), apontando para uma do segundo tipo que descreva o objeto por cada uma delas identificado. Opcionalmente, poderá ser realizada a verificação de existência do objeto antes do redirecionamento, retornando em vez disso o código HTTP 404, caso ele não exista na base de dados.

6. Dentre as URIs que identificam recursos informacionais, usar URIs sem extensão e também com extensão. As URIs sem extensão deveram ser usadas via de regra, sendo a referência persistente ao documento identificado. As URIs com extensão serão usadas apenas como uma forma de facilitar o download em um browser dos demais formatos (caso contrário o usuário precisaria de uma ferramenta especializada para essa simples tarefa), e identifica a versão naquele formato do recurso informacional referenciado. Sempre que possível, em cada representação, deve-se fornecer links para as URIs com extensão que levam às representações com formatos específicos.

7. Separar as consultas individuais e as coletivas. As individuais usam um slug {identificador} e as coletivas um slug {funcao}.

8. Em todos os slugs, separar as palavras por hifens (ex.: orgaos-entidades) para maior clareza na leitura e reduzir a possibilidade de ambiguidades.

9. Nos valores do slug {funcao}, não usar a palavra "consulta", Ex.: "dominio" em vez de "consultardominio". A informação de que se trata de uma consulta já está implícita pelo uso do verbo GET no protocolo HTTP.

10. No slug {referencia}, não é viável tecnicamente utilizar os parâmetros após o caractere de hash ("#"), uma vez que pela especificação do HTTP esse fragmento é descartado pelo cliente ao enviar a requisição ao servidor. Ou seja, ele é tratado apenas no cliente e o servidor não toma conhecimento desses parâmetros. Na falta de uma alternativa melhor, sugiro usar a tradicional separação de parâmetros, iniciando-se pela interrogação ("?") e os demais separadores, se houver, "&".

11. Ainda não entendi bem o que seriam as consultas do tipo "dominio" e "filha". Imaginando que seja algo específico do SIORG, as mantive.

12. Usar um fragmento identificador legível para humanos onde for possível. Dá algum trabalho, mas não é tão complicado quanto parece, e os benefícios são grandes. Fizemos um trabalho desse tipo ao gerar identificadores para os assuntos do VCGE. Estou ciente de que para alguns conceitos (ex.: unidade organizacional) isso é inviável, mas para outros (esfera, poder, natureza jurídica) é fácil e muito útil para quem vai utilizar.

13. Seguindo as melhores práticas do REST e o princípio "Hypermedia as the engine of the application state" (HATEOAS), devem ser indicados os relacionamentos entre objetos apontando não apenas a chave do objeto apontado, como também a URI que o identifica.

Todas essas sugestões estão incorporadas no documento anexo. Mandem as suas contribuições e vamos refinando a proposta, até aos poucos chegar no ideal.