diff --git a/src/dso_api/dynamic_api/urls.py b/src/dso_api/dynamic_api/urls.py index 0d97b7b2b..bb86f7c5b 100644 --- a/src/dso_api/dynamic_api/urls.py +++ b/src/dso_api/dynamic_api/urls.py @@ -13,25 +13,28 @@ def get_patterns(router_urls): """Generate the actual URL patterns for this file.""" return [ + # Doc endpoints path( - "docs/generic/.html", + "docs/generic/.html", GenericDocs.as_view(), name="docs-generic", ), path( - "docs/generic//.html", + "docs/generic//.html", GenericDocs.as_view(), name="docs-generic", ), path("docs/index.html", DocsOverview.as_view(), name="docs-index"), path("docs/search.html", search), path("docs/searchindex.json", search_index), + # Override some API endpoints: path( "haalcentraal/bag/", HaalCentraalBAG.as_view(), name="haalcentraal-bag" ), path( "haalcentraal/brk/", HaalCentraalBRK.as_view(), name="haalcentraal-brk" ), + # All API types: path("mvt/", views.DatasetMVTIndexView.as_view(), name="mvt-index"), path("wfs/", views.DatasetWFSIndexView.as_view()), path("", include(router_urls), name="api-root"), diff --git a/src/dso_api/dynamic_api/views/doc.py b/src/dso_api/dynamic_api/views/doc.py index 310ed9f17..51ba7b4b7 100644 --- a/src/dso_api/dynamic_api/views/doc.py +++ b/src/dso_api/dynamic_api/views/doc.py @@ -18,7 +18,6 @@ from django.urls import NoReverseMatch, reverse from django.utils.decorators import method_decorator from django.utils.safestring import mark_safe -from django.views import View from django.views.decorators.cache import cache_page from django.views.generic import TemplateView from markdown import Markdown @@ -68,66 +67,30 @@ def search_index(_request) -> HttpResponse: return JsonResponse(index) -@method_decorator(decorators, name="get") -class GenericDocs(View): +# @method_decorator(decorators, name="get") +class GenericDocs(TemplateView): """Documentation pages from ``/v1/docs/generic/...``.""" - PRE = f""" - - - - - Amsterdam DataPunt API Documentatie - - - - - -
- -

Introductie API Keys

-
-

- Het Dataplatform van de gemeente Amsterdam gaat het gebruik van een identificatie key - bij het aanroepen van haar API's vanaf 1 februari 2024 verplicht stellen. - Vanaf 1 februari 2024 kun je de API's van het Dataplatform niet meer zonder - een key gebruiken. Vraag tijdig een key aan via dit aanvraagformulier. - Doe je dit niet, dan werkt je applicatie of website vanaf 1 februari 2024 niet meer. - Dit geldt voor alle API's die op deze pagina gedocumenteerd zijn. -

-

- Door de API key kunnen we contact houden met de gebruikers van onze API's. - Zo kunnen we gebruikers informeren over updates. - Daarnaast krijgen we hiermee inzicht in het gebruik van de API's - en in wie welke dataset via de API bevraagt. - Ook voor dataeigenaren is dit waardevolle informatie. -

-

- Meer info:
- - Pagina API key aanvragen
- - Technische documentatie
- Vragen? Mail naar dataplatform@amsterdam.nl
-

-

+ template_name = "dso_api/dynamic_api/docs/rest/base.html" - """ - - POST = """
""" - - def get(self, request, category, topic="index", *args, **kwargs): - uri = request.build_absolute_uri(reverse("dynamic_api:api-root")) + def get_context_data(self, **kwargs): + category = self.kwargs["category"] + topic = self.kwargs.get("topic", "index") + uri = self.request.build_absolute_uri(reverse("dynamic_api:api-root")) template = f"dso_api/dynamic_api/docs/{category}/{topic}.md" try: md = render_to_string(template, context={"uri": uri}) except TemplateDoesNotExist as e: raise Http404() from e + html = markdown.convert(md) - return HttpResponse(self.PRE + html + self.POST) + html = html.replace("", '
') + + return { + "markdown_content": mark_safe(html), # noqa: S308 + "apikey_register_url": urljoin(settings.APIKEYSERV_API_URL, "/clients/v1/register/"), + "apikey_docs_url": urljoin(settings.APIKEYSERV_API_URL, "/clients/v1/docs/"), + } @method_decorator(decorators, name="dispatch") @@ -242,7 +205,7 @@ class LookupContext(NamedTuple): def lookup_context(op, example, descr): # disable mark_safe() warnings because this is static HTML in this very file. - return LookupContext(op, mark_safe(example), mark_safe(descr)) # noqa: B308, B703, S308 + return LookupContext(op, mark_safe(example), mark_safe(descr)) # noqa: S308 # This should match ALLOWED_SCALAR_LOOKUPS in filters.parser (except for the "exact" lookup). @@ -336,8 +299,7 @@ def _table_context(ds: Dataset, table: DatasetTableSchema): { "name": name, "type": "Datetime", - "value_example": "yyyy-mm-dd of " - "yyyy-mm-ddThh:mm[:ss[.ms]]", + "value_example": mark_safe(VALUE_EXAMPLES["date-time"]), # noqa: S308 } ) @@ -556,7 +518,7 @@ def _filter_payload( "name": name, "type": type.capitalize(), "is_deprecated": is_deprecated, - "value_example": mark_safe(value_example or ""), # noqa: B308, B703, S308 (is static HTML) + "value_example": mark_safe(value_example or ""), # noqa: S308 (is static HTML) "lookups": [LOOKUP_CONTEXT[op] for op in lookups], "auth": _fix_auth(field.auth | field.table.auth | field.table.dataset.auth), } diff --git a/src/dso_api/static/dso_api/dynamic_api/css/docs.css b/src/dso_api/static/dso_api/dynamic_api/css/docs.css new file mode 100644 index 000000000..a954e98bf --- /dev/null +++ b/src/dso_api/static/dso_api/dynamic_api/css/docs.css @@ -0,0 +1,34 @@ +/* Override bootstrap 3 defaults */ +body { line-height: 1.6; } + +a:not([href]) { color: inherit; } +a:not([href]):hover { color: inherit; text-decoration: none; } + +/* Inspired by readthedocs style */ +.tip, +.warning, +.danger, +.note { + padding: 12px; + margin: 12px 0 24px; + border-radius: 4px; + overflow: hidden; +} + +.note { background: #e7f2fa; } +.tip { background: #dbfaf4; } +.warning { background: #ffedcc; } +.danger { background: #fdf3f2; } + +.title { + font-weight: 700; + display: block; + color: #fff; + padding: 6px 12px; + margin: -12px -12px 12px; +} + +.note .title { background: #6ab0de; } +.tip .title { background: #1abc9c; } +.warning .title { background: #f0b37e; } +.danger .title { background: #f29f97; } diff --git a/src/templates/dso_api/dynamic_api/docs/dataset.html b/src/templates/dso_api/dynamic_api/docs/dataset.html index 2dd1d8835..2c023a8a6 100644 --- a/src/templates/dso_api/dynamic_api/docs/dataset.html +++ b/src/templates/dso_api/dynamic_api/docs/dataset.html @@ -1,10 +1,11 @@ -{% load i18n %} +{% load i18n static %} {% if schema.title %}{{ schema.title }}{% else %}{{ name|title }}{% endif %} — Amsterdam Datapunt API Documentatie v1 - - - + + + + {% block extrahead %}{% endblock %} @@ -78,7 +79,7 @@

{{ table.title }}

De volgende velden zijn beschikbaar:

-
+
@@ -110,7 +111,7 @@

{{ table.title }}

Veldnaam

De volgende query-parameters zijn te gebruiken:

- +
@@ -154,7 +155,7 @@

{{ table.title }}

{% if table.expands %}

Insluitbare relaties

De volgende velden kunnen ingesloten worden met ?_expandScope=...:

-
Parameter
+
diff --git a/src/templates/dso_api/dynamic_api/docs/dataset_wfs.html b/src/templates/dso_api/dynamic_api/docs/dataset_wfs.html index ad2cb27f6..0c8c52b10 100644 --- a/src/templates/dso_api/dynamic_api/docs/dataset_wfs.html +++ b/src/templates/dso_api/dynamic_api/docs/dataset_wfs.html @@ -1,11 +1,12 @@ - +{% load static %} {{ schema.title }} - - - + + + +
diff --git a/src/templates/dso_api/dynamic_api/docs/overview.html b/src/templates/dso_api/dynamic_api/docs/overview.html index 1113006ce..77aec22ad 100644 --- a/src/templates/dso_api/dynamic_api/docs/overview.html +++ b/src/templates/dso_api/dynamic_api/docs/overview.html @@ -1,11 +1,12 @@ - +{% load static %} Amsterdam DataPunt API Documentatie - - - + + + +
diff --git a/src/templates/dso_api/dynamic_api/docs/rest/base.html b/src/templates/dso_api/dynamic_api/docs/rest/base.html new file mode 100644 index 000000000..330fd96a3 --- /dev/null +++ b/src/templates/dso_api/dynamic_api/docs/rest/base.html @@ -0,0 +1,43 @@ +{% load static %} + + + + Amsterdam DataPunt API Documentatie + + + + + + +
+ +

Introductie API Keys

+
+

+ Het Dataplatform van de gemeente Amsterdam gaat het gebruik van een identificatie key + bij het aanroepen van haar API's vanaf 1 februari 2024 verplicht stellen. + Vanaf 1 februari 2024 kun je de API's van het Dataplatform niet meer zonder + een key gebruiken. Vraag tijdig een key aan via dit aanvraagformulier. + Doe je dit niet, dan werkt je applicatie of website vanaf 1 februari 2024 niet meer. + Dit geldt voor alle API's die op deze pagina gedocumenteerd zijn. +

+

+ Door de API key kunnen we contact houden met de gebruikers van onze API's. + Zo kunnen we gebruikers informeren over updates. + Daarnaast krijgen we hiermee inzicht in het gebruik van de API's + en in wie welke dataset via de API bevraagt. + Ook voor dataeigenaren is dit waardevolle informatie. +

+

+ Meer info:
+ Pagina API key aanvragen
+ Technische documentatie
+ Vragen? Mail naar dataplatform@amsterdam.nl
+

+

+ +{{ markdown_content }} + +
+ + diff --git a/src/templates/dso_api/dynamic_api/docs/search.html b/src/templates/dso_api/dynamic_api/docs/search.html index dd1f110b2..ccc60a6bf 100644 --- a/src/templates/dso_api/dynamic_api/docs/search.html +++ b/src/templates/dso_api/dynamic_api/docs/search.html @@ -2,9 +2,10 @@ Amsterdam Datapunt API Documentatie v1 - - - + + + + {% block extrahead %}{% endblock %}
Relatie