From 3aeb6e4710e9b18dfae81f303d5c3aee4c9a516e Mon Sep 17 00:00:00 2001 From: Bernardo Fontes Date: Wed, 11 Nov 2020 16:30:41 -0300 Subject: [PATCH 1/7] =?UTF-8?q?Implementa=20docs=20din=C3=A2micos=20para?= =?UTF-8?q?=20a=20API?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- api/docs/__init__.py | 0 api/docs/views.py | 10 ++++ api/templates/api/docs.html | 51 ++++++++++++++++++++ api/templates/api/snippets/dataset_docs.html | 24 +++++++++ brasilio/urls.py | 3 ++ 5 files changed, 88 insertions(+) create mode 100644 api/docs/__init__.py create mode 100644 api/docs/views.py create mode 100644 api/templates/api/docs.html create mode 100644 api/templates/api/snippets/dataset_docs.html 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..c3d62437 --- /dev/null +++ b/api/docs/views.py @@ -0,0 +1,10 @@ +from django.shortcuts import render + +from core.models import Dataset + + +def dynamic_api_docs_view(request): + context = { + "datasets": Dataset.objects.api_visible(), + } + 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..36052dc1 --- /dev/null +++ b/api/templates/api/docs.html @@ -0,0 +1,51 @@ +{% 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

+ + + Legendas +
    +
  • Campos que permitem filtragem via query string na URL
    • +
+
+
+
+
+ +

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.brasil.io/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..e22e429c --- /dev/null +++ b/api/templates/api/snippets/dataset_docs.html @@ -0,0 +1,24 @@ +

{{ dataset.name }}

+
+ +

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

+

curl -X GET -k -H 'Authorization: Token 123412341234' -i 'https://api.brasil.io/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.brasil.io/v1/dataset/{{ dataset.slug }}/{{ table.name }}/data/'

+
Colunas
+ + + {% endif %} + +{% endfor %} diff --git a/brasilio/urls.py b/brasilio/urls.py index 27616a6c..828942f3 100644 --- a/brasilio/urls.py +++ b/brasilio/urls.py @@ -3,9 +3,12 @@ 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/", include("brasilio.api_urls")), + path("documentacao-api/", dynamic_api_docs_view, name="api_docs"), path("auth/", include("brasilio_auth.urls", namespace="brasilio_auth")), path("covid19/", include("covid19.urls", namespace="covid19")), path("django-rq/", include("django_rq.urls")), From c6443db7583921657a685c9e8be844d6507ed424 Mon Sep 17 00:00:00 2001 From: Bernardo Fontes Date: Wed, 11 Nov 2020 16:35:24 -0300 Subject: [PATCH 2/7] Adiciona link para docs no menu --- core/templates/core/menu.html | 1 + 1 file changed, 1 insertion(+) 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
  • From 91f7ed5607f2e5228c468bf53237f9e456c4d3b0 Mon Sep 17 00:00:00 2001 From: Bernardo Fontes Date: Wed, 11 Nov 2020 16:38:51 -0300 Subject: [PATCH 3/7] =?UTF-8?q?=C3=A2ncora=20para=20sess=C3=A3o=20"dataset?= =?UTF-8?q?s"?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- api/templates/api/docs.html | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/api/templates/api/docs.html b/api/templates/api/docs.html index 36052dc1..e0d2fe61 100644 --- a/api/templates/api/docs.html +++ b/api/templates/api/docs.html @@ -17,6 +17,7 @@

    Índice

    • Autenticação
      • +
    • Datasets
      • {% for dataset in datasets %}
    • {{ dataset.name }}
      • {% endfor %} @@ -38,7 +39,7 @@

      Autenticação

      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

      +

      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.brasil.io/v1/datasets/'

      From 7b46f3e50dff7d2ae66204352cf0cd8fda28cd1c Mon Sep 17 00:00:00 2001 From: Bernardo Fontes Date: Fri, 27 Nov 2020 16:11:27 -0300 Subject: [PATCH 4/7] Atualiza URL --- brasilio/urls.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/brasilio/urls.py b/brasilio/urls.py index 828942f3..f2fd6b23 100644 --- a/brasilio/urls.py +++ b/brasilio/urls.py @@ -7,8 +7,8 @@ urlpatterns = [ path("admin/", admin.site.urls), + path("api/docs/", dynamic_api_docs_view, name="api_docs"), path("api/", include("brasilio.api_urls")), - path("documentacao-api/", dynamic_api_docs_view, name="api_docs"), path("auth/", include("brasilio_auth.urls", namespace="brasilio_auth")), path("covid19/", include("covid19.urls", namespace="covid19")), path("django-rq/", include("django_rq.urls")), From 793e77b3576c45f6499a9fb35d28c0db34df1c63 Mon Sep 17 00:00:00 2001 From: Bernardo Fontes Date: Fri, 27 Nov 2020 16:19:34 -0300 Subject: [PATCH 5/7] Recupera host de api do settings --- api/docs/views.py | 2 ++ api/templates/api/docs.html | 2 +- api/templates/api/snippets/dataset_docs.html | 4 ++-- 3 files changed, 5 insertions(+), 3 deletions(-) diff --git a/api/docs/views.py b/api/docs/views.py index c3d62437..f68c47c0 100644 --- a/api/docs/views.py +++ b/api/docs/views.py @@ -1,3 +1,4 @@ +from django.conf import settings from django.shortcuts import render from core.models import Dataset @@ -6,5 +7,6 @@ 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 index e0d2fe61..103c87cb 100644 --- a/api/templates/api/docs.html +++ b/api/templates/api/docs.html @@ -42,7 +42,7 @@

      Autenticação

      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.brasil.io/v1/datasets/'

      +

      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 %} diff --git a/api/templates/api/snippets/dataset_docs.html b/api/templates/api/snippets/dataset_docs.html index e22e429c..1cd95041 100644 --- a/api/templates/api/snippets/dataset_docs.html +++ b/api/templates/api/snippets/dataset_docs.html @@ -2,14 +2,14 @@

      {{ dataset.name }}

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

      -

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

      +

      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.brasil.io/v1/dataset/{{ dataset.slug }}/{{ table.name }}/data/'

      +

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

      Colunas
        From fb96179b85bcfd2979ec8ab7aaa7e367959a1c65 Mon Sep 17 00:00:00 2001 From: Bernardo Fontes Date: Fri, 27 Nov 2020 16:28:39 -0300 Subject: [PATCH 6/7] =?UTF-8?q?Simplifica=20renderica=C3=A7=C3=A3o=20dos?= =?UTF-8?q?=20campos=20removendo=20descri=C3=A7=C3=A3o=20e=20adicionando?= =?UTF-8?q?=20tipos?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- api/templates/api/snippets/dataset_docs.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/templates/api/snippets/dataset_docs.html b/api/templates/api/snippets/dataset_docs.html index 1cd95041..bc95faad 100644 --- a/api/templates/api/snippets/dataset_docs.html +++ b/api/templates/api/snippets/dataset_docs.html @@ -15,7 +15,7 @@
        Colunas
          {% for field in table.fields %} {% if field.show %} -
        • {% if field.frontend_filter %} {% endif %}{{ field.name }} ({{ field.title }}){% if field.description %}: {{ field.description }}{% endif %}
          • +
        • {{ field.name }} ({{ field.get_type_display }}): {{ field.title }}
          • {% endif %} {% endfor %}
        From dadf8b0fc0f472cb8f098b55a89cc92883f63b46 Mon Sep 17 00:00:00 2001 From: Bernardo Fontes Date: Fri, 27 Nov 2020 16:36:41 -0300 Subject: [PATCH 7/7] =?UTF-8?q?Adiciona=20=C3=ADcones=20sobre=20os=20campo?= =?UTF-8?q?s?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- api/templates/api/docs.html | 5 ----- api/templates/api/snippets/dataset_docs.html | 19 ++++++++++++++++--- 2 files changed, 16 insertions(+), 8 deletions(-) diff --git a/api/templates/api/docs.html b/api/templates/api/docs.html index 103c87cb..2ec9b22c 100644 --- a/api/templates/api/docs.html +++ b/api/templates/api/docs.html @@ -22,11 +22,6 @@
      • {{ dataset.name }}
        • {% endfor %}
      - - Legendas -
        -
      • Campos que permitem filtragem via query string na URL
        • -
      diff --git a/api/templates/api/snippets/dataset_docs.html b/api/templates/api/snippets/dataset_docs.html index bc95faad..895c9ca5 100644 --- a/api/templates/api/snippets/dataset_docs.html +++ b/api/templates/api/snippets/dataset_docs.html @@ -14,9 +14,22 @@
      Colunas
        {% for field in table.fields %} - {% if field.show %} -
      • {{ field.name }} ({{ field.get_type_display }}): {{ field.title }}
        • - {% endif %} +
      • {{ field.name }} ({{ field.get_type_display }}) + + {% if field.show %} + {% if field.show_on_frontend %}{% endif %} + {% if not field.show_on_frontend %}{% endif %} + {% else %} + {% if not field.show_on_frontend %}{% endif %} + {% endif %} + + {% if field.frontend_filter %}{% endif %} + + {% if field.searchable %}{% endif %} + + {% if field.has_choices %}{% endif %} + + : {{ field.title }}
        • {% endfor %}
      {% endif %}