APIs.json permite aos domínios tornarem as suas APIs públicas e indexáveis por buscadores.
O APIs.json é uma especificação de formato utilizado para definir APIs. Essa especificação fica no arquivo localizado na raiz do domínio, contendo a descrição das APIs e links para outros arquivos similares. O APIs.json é similar ao robots.txt usado pelos buscadores para indexar o conteúdo de um site web, mas aplicando-se à descoberta e indexação de APIs.
Apesar do APIs.json estar somente na versão 0.14, os autores o consideram "pronta para uso" e "algo que as comunidades podem usar para construir suas soluções". O formato define um conjunto de elementos obrigatórios e opcionais. Alguns desses elementos são:
- Name (obrigatório): texto legível com o nome da coleção de APIs;
- Description (obrigatório): descrição da coleção de APIs;
- Created (obrigatório): data de criação do arquivo;
- APIs (opcional): lista de APIs identificadas no arquivo, cada uma contendo:
- Name (obrigatório): nome da API;
- Description (obrigatório): texto legível descrevendo a API;
- baseUrl (obrigatório): URL da API ou endpoint primário;
- Version (opcional): versão da API na qual a descrição se refere;
- Properties (opcional):
O APIs.json é o resultado do esforço conjunto da 3Scale e do API Evangelist (site que aborda diversos assuntos relacionados ao uso de APIs) . O InfoQ.com entrevistou Kin Lane da API Evangelist para saber mais detalhes a respeito desse projeto.
InfoQ.com: Há intenção de submeter esse formato para ser aprovado como um padrão?
Lane: A submissão para se tornar um padrão é um futuro possível para o APIs.json. Mas por enquanto estamos trabalhando para obter o máximo possível de comentários sobre o formato e para chegar à maturidade com o uso em 1000 domínios. Somente após isso consideraremos os próximos passos.
InfoQ.com: Algum site já está usando esse formato?
Lane: O primeiro foi o API Evangelist, mas há 138 APIs submetidas por 98 provedores diferentes, porém muitos deles não são provedores oficiais. Isso significa que elas foram submetidas por terceiros. Contudo, há muitas APIs oficiais de provedores como Spotify, Diffbot, Paypal, MYOB e Neutrino API.
InfoQ.com: Por que a versão atual é a 0.14 sendo que ela já pode ser usada pela comunidade? Ela não deveria ser 1.0?
Lane: Começamos com a versão 0.11 e rapidamente coletamos comentários. Vários eventos levaram à versão 0.14. Até que ela seja usada de forma abrangente e que algumas centenas de provedores tenham o consenso de que ela funciona, a versão 1.0 não parece ser apropriada. Levamos alguns longos meses para chegar onde chegamos, mas ainda temos muito trabalho a fazer.
InfoQ.com: O APIs.json dá suporte aos seguintes formatos: Swagger, RAML, Blueprint, WADS e WSDL. Existem planos para dar suporte a outros formatos no futuro?
Lane: Optamos por manter o foco nos principais formatos de definição de APIs no lançamento. Contudo, utilizando as propriedades das APIs na especificação é possível escolher qualquer formato desejado. Não há limitações, e uma vez que um formato passe a ser mais utilizado ele será incluído na especificação principal.
InfoQ.com: Quais são os planos para o futuro próximo e o distante?
Lane: Implementar, implementar e implementar. Estamos educando os provedores de API sobre o APIs.json e ajudando-os a implementá-las. Nosso foco será ajudar as pessoas a entenderem os benefícios sobre o uso interno do APIs.json, bem como sobre torná-las localizáveis publicamente. Em paralelo continuaremos trabalhando no ferramental significativo, tal como o buscador de código aberto APIs.io, que ajuda as pessoas à verem os benefícios do APIs.json.
O APIs.json vem acompanhado do APIs.io, um buscador de código aberto que procura na web os arquivos apis.json e os indexa. O site também contém ferramentas para registrar novas APIs, gerar e validar os arquivos apis.json para o domínio.
O projeto APIs.json está inteiramente disponível no GitHub sob a licença MIT.