O que é realmente importante e útil numa API RESTful?

por Fabricio Rocha
Autor da pesquisa, jornalista, integrante
da Seção de Integração a Serviços Externos de
Interação Social (SISEI) da Câmara dos Deputados
http://lattes.cnpq.br/3751514686843021

Os atuais padrões criados para a chamada "web semântica" e o movimento "linked data", tão apoiado pelo pai da web Tim Berners-Lee, não estão lá com muita moral junto aos desenvolvedores brasileiros que trabalham com APIs de dados abertos. Essa é uma das possíveis conclusões a uma pesquisa online realizada informalmente pelo serviço de Dados Abertos da Câmara dos Deputados, em 17 dias entre junho e julho de 2016, que perguntou aos hackers o que é realmente útil ou importante numa interface RESTful de fornecimento de dados.

O formulário da pesquisa ofereceu aos entrevistados uma lista de 30 conceitos e ideias defendidos por escritores e autoridades em webservices REST ‒ algumas delas divergentes ‒ para que cada item recebesse uma nota de 1 a 5. Após a divulgação feita ao grupo "Dados Abertos.BR" no Telegram e por e-mails a desenvolvedores cadastrados no LabHacker da Câmara, a pesquisa foi respondida por 41 participantes, um número maior do que o esperado.

Uma das surpresas reveladas pela enquete veio junto com um problema. O fornecimento de dados em formato XML, que é parte vital de padrões para fornecimento de dados governamentais como LexBR e Akoma Ntoso, foi apenas o quarto formato na ordem de preferência dos desenvolvedores, com nota média de 2,976, no 19º lugar na lista de itens considerados mais importantes. E seu derivado semântico XML+RDFa, recomendado pelo W3C, ficou no último lugar geral, com média 2,463.

Aparentemente, a prolixidade e a complexidade no processamento de dados em XML e seus derivados fazem com que os programadores prefiram os formatos mais simples e compactos: o cada vez mais popular JSON é o predileto, com nota 4,098, a segunda melhor média geral, e o veterano e humilde formato CSV, de texto puro formatado como tabelas, foi o segundo formato preferido com média 3,561. Ainda à frente do XML ficou o JSONP, que cravou a média 3. E dando sinais de que há algo de errado com os formatos semânticos, o JSON-LD, também recomendado pelo W3C, não se saiu bem na votação e obteve a média 2,659.

Independentemente de formato, mesmo o uso de vocabulários internacionais (como Dublin Core e Schema.org) para identificar as informações ainda não é algo visto como muito útil pelos programadores brasileiros: a média de avaliações foi 2,78. A idéia de receber metadados juntos com todos os dados requisitados também parece ser desagradável, com média de 2,829 ‒ mais bem vista é a proposta de receber metadados por meio de requisições opcionais, que teve média 3,073. Talvez a simplificação das formas de entrega e uso de metadados faça com que, com o tempo, os desenvolvedores vejam mais utilidade e possibilidades de inovação nesses recursos.

O que os hackers brasileiros consideram mais importante é documentação e padronização dos dados e suas estruturas, mais no sentido de coerência do que no sentido de comitês e instituições. A existência de páginas sucintas de "auto-documentação" gerada do próprio código dos servidores, como popularizado pelo sistema Swagger, foi bem avaliada com a média 3,976 ‒ mas o maior grau de importância de toda a pesquisa foi dado à existência de um portal de documentação abrangente sobre as opções de requisição e as informações retornadas. Links para a documentação incorporados aos dados foram também bem avaliados, com nota 3,171. É de se presumir, portanto, que a idéia de dados auto-descritivos e processamento automatizado ainda é vista com desconfiança pelos desenvolvedores.

E aí, você concorda ou discorda das análises apresentadas aqui? Dê uma olhada nos resultados completos da pesquisa e deixe um comentário com as suas interpretações dos números!

Questão	Média das respostas
Portal de documentação, com descrições dos dados retornados e das opções para cada requisição	4,488
Possibilidade de receber dados em formato JSON	4,098
Parâmetros de query strings sempre com os mesmos nomes, em diferentes endpoints da API	4,073
Possibilidade de receber notificações sobre alguma atualização dos dados (PUSH)	3,976
Uma página Swagger com a documentação mínima sobre toda a API	3,976
Em dados compostos, obtidos por diferentes endpoints, usar "blocos" (nós XML, propriedades JSON) padronizados em estrutura e identificados sempre pelos mesmos nomes	3,732
Datas e horários uniformizados em formato AAAA-MM-DDThh-mm-ss	3,732
Códigos de erros mais específicos do que 404 (Not Found) e 500 (Server Error)	3,707
Possibilidade de receber dados em formato CSV	3,561
Links de paginação (próximo, anterior, etc) em listagens parciais retornadas pelos endpoints	3,537
Possibilidade de escolher o "encoding" dos dados retornados	3,220
Cada unidade de dados conter um link para a documentação sobre ela	3,171
Em endpoints que retornam listagens, cada unidade de dados retornada ter apenas informações essenciais para permitir uma busca detalhada se necessário	3,098
Receber descrições semânticas (de algum vocabulário) para cada campo de dados, mas separada dos dados em si, por requisição separada e opcional	3,073
Atendimento a requisições HTTP OPTIONS, para cada endpoint, retornando dados processáveis sobre a API	3,024
Possibilidade de receber dados em formato JSONP	3,000
Em endpoints que retornam listagens, cada unidade de dados conter o máximo de informação possível, para evitar novas requisições	3,000
Possibilidade de receber dados em formato XML	2,976
Links para fotos em todas as unidades de dados referentes a pessoas	2,951
Para cada campo com um dado simples, prefixar o nome com algo que dê pista sobre o tipo de dado (p.ex., "strNomeDeputado")	2,951
Cabeçalho "Content-Length" nas respostas do servidor	2,902
Datas e horários uniformizados em formato Unix Epoch (int 32)	2,854
Receber descrições semânticas (de algum vocabulário) para cada campo de dados, como parte dos próprios dados, em cada unidade retornada (inclusive de listagens)	2,829
Uso de vocabulários populares e genéricos (Dublin Core, FOAF ou Schema.org) em descrições dos campos de dados retornados	2,780
Atendimento a requisições HTTP OPTIONS, para cada endpoint, retornando documentação "para humanos" sobre a API	2,707
Códigos de sucesso mais específicos do que 200 (OK)	2,707
Possibilidade de receber dados em formato JSON-LD	2,659
Cada unidade de dados identificada com um link para "self"	2,488
Atendimento a requisições HTTP HEAD em cada endpoint	2,488
Possibilidade de receber dados em formato XML+RDFa	2,463