diff --git a/api/docs/__init__.py b/api/docs/__init__.py new file mode 100644 index 00000000..e69de29b diff --git a/api/docs/views.py b/api/docs/views.py new file mode 100644 index 00000000..f68c47c0 --- /dev/null +++ b/api/docs/views.py @@ -0,0 +1,12 @@ +from django.conf import settings +from django.shortcuts import render + +from core.models import Dataset + + +def dynamic_api_docs_view(request): + context = { + "datasets": Dataset.objects.api_visible(), + "api_host": settings.BRASILIO_API_HOST, + } + return render(request, "api/docs.html", context=context) diff --git a/api/templates/api/docs.html b/api/templates/api/docs.html new file mode 100644 index 00000000..2ec9b22c --- /dev/null +++ b/api/templates/api/docs.html @@ -0,0 +1,47 @@ +{% extends "base.html" %} + +{% block title %}Documentação da API{% endblock %} + +{% block content %} + +
+
+
+
+
+

Documentação da API

+

Aqui você pode encontrar a listagem de todos os datasets, tabelas e campos disponíveis na API do Brasil.io. Além disso, você também encontrará informações sobre como fazer requisições para a API respeitando a autenticação.

+

Importante: Utilizar a API desnecessariamente e de maneira não otimizada onera muito nossos servidores e atrapalha a experiência de outros usuários. Por conta disso, nessa documentação vocè também encontrará os links para os arquivos de dados completos de todos os datasets.

+ +
+

Índice

+ +
+
+
+
+ +

Autenticação

+
+

Para ter mais contexto sobre os porquês dessa autenticação, leia o nosso blogpost "Nossa API será obrigatoriamente autenticada".

+

A API do Brasil.IO implementa utilizando o cabeçalho HTTP Authorizaton. Ela espera que o valor desse cabeçalho seja sempre algo no formato Token sua_chave_de_api_aqui. Este é um exemplo de uma requisição para a raiz da API utilizando o Curl:

+

curl -X GET -k -H 'Authorization: Token 123412341234' -i 'https://api.brasil.io/v1/'

+

Para criar e gerenciar suas chaves de API, autentique-se no sistema e acesse a página Chaves da API.

+ +

Datasets

+
+

Exemplo de requisição para listar todos os datasets disponíveis na API do Brasil.io:

+

curl -X GET -k -H 'Authorization: Token 123412341234' -i 'https://{{ api_host }}/v1/datasets/'

+ + {% for dataset in datasets %} + {% include "api/snippets/dataset_docs.html" with dataset=dataset %} + {% endfor %} + +
+{% endblock %} diff --git a/api/templates/api/snippets/dataset_docs.html b/api/templates/api/snippets/dataset_docs.html new file mode 100644 index 00000000..895c9ca5 --- /dev/null +++ b/api/templates/api/snippets/dataset_docs.html @@ -0,0 +1,37 @@ +

{{ dataset.name }}

+
+ +

Exemplo de requisição para apresentar informações sobre esse dataset:

+

curl -X GET -k -H 'Authorization: Token 123412341234' -i 'https://{{ api_host }}/v1/dataset/{{ dataset.slug }}/'

+

O dataset completo pode ser baixado diretamente nesta página. Por favor, dê preferência a baixar o dataset completo caso você vá precisar de todos aos dados ao invés de utilizar a API.

+ +{% for table in dataset.tables %} + {% if table.api_enabled %} +
Tabela {{ table.name }}
+

Exemplo de requisição para os dados desta tabela:

+

curl -X GET -k -H 'Authorization: Token 123412341234' -i 'https://{{ api_host }}/v1/dataset/{{ dataset.slug }}/{{ table.name }}/data/'

+
Colunas
+ + + {% endif %} + +{% endfor %} diff --git a/brasilio/urls.py b/brasilio/urls.py index 27616a6c..f2fd6b23 100644 --- a/brasilio/urls.py +++ b/brasilio/urls.py @@ -3,8 +3,11 @@ from django.contrib import admin from django.urls import include, path +from api.docs.views import dynamic_api_docs_view + urlpatterns = [ path("admin/", admin.site.urls), + path("api/docs/", dynamic_api_docs_view, name="api_docs"), path("api/", include("brasilio.api_urls")), path("auth/", include("brasilio_auth.urls", namespace="brasilio_auth")), path("covid19/", include("covid19.urls", namespace="covid19")), diff --git a/core/templates/core/menu.html b/core/templates/core/menu.html index 82aaf25d..d8bf600d 100644 --- a/core/templates/core/menu.html +++ b/core/templates/core/menu.html @@ -32,6 +32,7 @@
  • Datasets
  • Páginas Especiais
  • API
    • +
  • API Docs