From f3ee6c8bad8524a27525eb4c9d578d0bf47ae525 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matthias=20Schl=C3=B6gl?= Date: Wed, 27 Mar 2024 15:52:55 +0100 Subject: [PATCH] docs(history): add basic doc for new history plugin --- docs/source/customization.rst | 8 +++++++ docs/source/history.rst | 39 +++++++++++++++++++++++++++++++++++ docs/source/index.rst | 1 + 3 files changed, 48 insertions(+) create mode 100644 docs/source/history.rst diff --git a/docs/source/customization.rst b/docs/source/customization.rst index e52f60224..efa111865 100644 --- a/docs/source/customization.rst +++ b/docs/source/customization.rst @@ -13,6 +13,14 @@ In standard APIS those models are * :class:`apis_core.collections.models.SkosCollection` * :class:`apis_core.collections.models.SkosCollectionContentObject` +The :py:mod:`apis_core.history` module also uses the generic views for +its models. This means that you can use the generic views for the historical +models of your own ontology. E.g. if you have a model ``Person`` in your +`apis_ontology.models` module, you can use the generic views for it. +`/apis/apis_ontology.historicalperson/`_ +will be the URL for the list view of the historical model. +`/apis/api/apis_ontology.historicalperson/`_ for the API view. + If you want to use the generic app for your own model, simple make your model inherit from :class:`apis_core.generic.abc.GenericModel`. diff --git a/docs/source/history.rst b/docs/source/history.rst new file mode 100644 index 000000000..cd2ab6ee2 --- /dev/null +++ b/docs/source/history.rst @@ -0,0 +1,39 @@ +History plugin +============== + +The :py:mod:`apis_core.history` module provides versioning +to the APIS framework. It is based on the `django-simple-history`_ +package. + +VersionMixin +------------ + +The :py:class:`apis_core.history.models.VersionMixin` class is a mixin +that can be added to any model to enable versioning. It adds a `history` +property to the model that returns a `HistoricalRecords` instance. Additionally +it allows to override the date of the revision by setting the `_history_date` +property of the model instance. +To activate versioning for a model, simply inherit from `VersionMixin`: +```python +from django.db import models +from apis_core.apis_history.models import VersionMixin + +class MyModel(VersionMixin, models.Model): + pass +``` + +API endpoint +------------ + +The :py:class:`apis_core.history.api_views.GenericHistoryLogs` class is a viewset +that provides a REST API endpoint for the version history of a model. It can be +used to retrieve the version history of a model instance. +The viewset can be accessed under `/apis/api/history/entity/edit_log/`. It takes +two mandatory query parameters: `id` and `entity_type`. The `id` parameter is the +primary key of the model instance and the `entity_type` parameter is the name of +the model class. The viewset returns a list of historical revisions of the model +instance. It is also included in the `apis_core` API schema. The swagger documentation +can be accessed under `/apis/swagger/schema/swagger-ui/#/apis/apis_api_history_entity_edit_log_list`. + + +.. _django-simple-history: https://django-simple-history.readthedocs.io/en/latest/ diff --git a/docs/source/index.rst b/docs/source/index.rst index 39927dcca..6b9c505b6 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -16,6 +16,7 @@ Welcome to APIS's documentation! settings customization user_documentation + history data_model glossary development