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
- Este produto pretende orientar a criação e manutenção de identificadores únicos dos recursos informacionais da INDA. O objetivo é padronizar o ambiente de referenciação e recuperação de informações e dados e auxiliar o processo de garantia da sua disponibilidade.
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
- Criação ou adoção de diretrizes para criação e manutenção de URIs.
Tópicos tratados
Documentos
Cronograma
| Produto / Atividade | Responsável | Status | Prazo |
|---|
| Avaliar o documento Designing URI sets for the UK public sector | Marcos Fernandes | concluído | 16/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.