✨ [#38] document api list endpoint

src/woo_publications/api/openapi.yaml

@@ -10,6 +10,132 @@ info:
     name: EUPL
     url: https://github.com/GeneriekPublicatiePlatformWoo/registratie-component/blob/main/LICENSE.md
 paths:
+  /api/v1/documenten:
+    get:
+      operationId: documentenList
+      description: Returns a paginated result list of existing documents.
+      summary: All available documents.
+      parameters:
+      - in: header
+        name: Audit-Remarks
+        schema:
+          type: string
+        description: |2
+
+          Any additional information describing the action performed by the user.
+        required: true
+      - in: header
+        name: Audit-User-ID
+        schema:
+          type: string
+        description: |2
+
+          The system identifier that uniquely identifies the user performing the action.
+          Ideally, this is obtained from some Identity and Access Management infrastructure.
+          With OpenID Connect, this would typically be the `sub` claim.
+        required: true
+      - in: header
+        name: Audit-User-Representation
+        schema:
+          type: string
+        description: |2
+
+          The display name of the user performing the action, to make them recognizable.
+        required: true
+      - name: page
+        required: false
+        in: query
+        description: A page number within the paginated result set.
+        schema:
+          type: integer
+      - in: query
+        name: publication
+        schema:
+          type: string
+          format: uuid
+        description: Search the document based on the unique identifier that represents
+          a publication..
+      - in: query
+        name: sorteer
+        schema:
+          type: array
+          items:
+            type: string
+            enum:
+            - -creatiedatum
+            - -officiele_titel
+            - -verkorte_titel
+            - creatiedatum
+            - officiele_titel
+            - verkorte_titel
+        description: |-
+          Sorteren op.
+
+          * `creatiedatum` - Creatiedatum
+          * `-creatiedatum` - Creatiedatum (aflopend)
+          * `officiele_titel` - Officiele titel
+          * `-officiele_titel` - Officiele titel (aflopend)
+          * `verkorte_titel` - Verkorte titel
+          * `-verkorte_titel` - Verkorte titel (aflopend)
+        explode: false
+        style: form
+      tags:
+      - Documenten
+      responses:
+        '200':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PaginatedDocumentList'
+          description: ''
+  /api/v1/documenten/{identifier}:
+    get:
+      operationId: documentenRetrieve
+      description: Retrieve a specific document.
+      summary: Retrieve a specific document.
+      parameters:
+      - in: header
+        name: Audit-Remarks
+        schema:
+          type: string
+        description: |2
+
+          Any additional information describing the action performed by the user.
+        required: true
+      - in: header
+        name: Audit-User-ID
+        schema:
+          type: string
+        description: |2
+
+          The system identifier that uniquely identifies the user performing the action.
+          Ideally, this is obtained from some Identity and Access Management infrastructure.
+          With OpenID Connect, this would typically be the `sub` claim.
+        required: true
+      - in: header
+        name: Audit-User-Representation
+        schema:
+          type: string
+        description: |2
+
+          The display name of the user performing the action, to make them recognizable.
+        required: true
+      - in: path
+        name: identifier
+        schema:
+          type: string
+          title: Identificatie
+          description: De (primaire) unieke identificatie.
+        required: true
+      tags:
+      - Documenten
+      responses:
+        '200':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Document'
+          description: ''
   /api/v1/informatiecategorieen:
     get:
       operationId: informatiecategorieenList
@@ -904,6 +1030,61 @@ components:
       - url
       - vertrouwelijkheidaanduiding
       - zaaktypen
+    Document:
+      type: object
+      properties:
+        identifier:
+          type: string
+          title: Identificatie
+          description: De (primaire) unieke identificatie.
+          maxLength: 255
+        publicatie:
+          type: integer
+          description: De publicatie waaronder dit document valt. Een publicatie kan
+            nul of meer documenten bevatten.
+        officieleTitel:
+          type: string
+          title: Officiële titel
+          maxLength: 255
+        verkorteTitel:
+          type: string
+          maxLength: 255
+        omschrijving:
+          type: string
+        creatiedatum:
+          type: string
+          format: date
+          description: De datum waarop het document ontstaan is. Niet te verwarren
+            met de registratiedatum - de creatiedatum valt typisch *voor* de registratiedatum.
+        bestandsformaat:
+          type: string
+          description: TODO - placeholder accepting anything, in the future this will
+            be validated against a reference value list.
+          maxLength: 255
+        bestandsnaam:
+          type: string
+          description: Bestandsnaam 'op de harde schijf' van het document, bijvoorbeeld
+            'gelakt-verslag.pdf'.
+          maxLength: 255
+        bestandsomvang:
+          type: integer
+          maximum: 2147483647
+          minimum: 0
+          description: Bestandsgrootte op de harde schijf, in bytes.
+        registratiedatum:
+          type: string
+          format: date-time
+          readOnly: true
+          title: Geregistreerd op
+          description: Systeemdatum en -tijd wanneer de publicatie in de databank
+            opgeslagen is. Niet te verwarren met de creatiedatum van de publicatie,
+            die typisch *voor* de registratiedatum valt.
+      required:
+      - creatiedatum
+      - identifier
+      - officieleTitel
+      - publicatie
+      - registratiedatum
     InformationCategory:
       type: object
       properties:
@@ -1002,6 +1183,29 @@ components:
         * `solijst` - Collaborative organisations list
         * `oorglijst` - Alternative government organisations
         * `zelf_toegevoegd` - Zelf-toegevoegd item
+    PaginatedDocumentList:
+      type: object
+      required:
+      - count
+      - results
+      properties:
+        count:
+          type: integer
+          example: 123
+        next:
+          type: string
+          nullable: true
+          format: uri
+          example: http://api.example.org/accounts/?page=4
+        previous:
+          type: string
+          nullable: true
+          format: uri
+          example: http://api.example.org/accounts/?page=2
+        results:
+          type: array
+          items:
+            $ref: '#/components/schemas/Document'
     PaginatedInformationCategoryList:
       type: object
       required:

src/woo_publications/api/urls.py

@@ -9,12 +9,16 @@
     OrganisationViewSet,
     ThemeViewSet,
 )
-from woo_publications.publications.api.viewsets import PublicationViewSet
+from woo_publications.publications.api.viewsets import (
+    DocumentViewSet,
+    PublicationViewSet,
+)
 
 app_name = "api"
 
 router = routers.DefaultRouter(trailing_slash=False)
 
+router.register("documenten", DocumentViewSet)
 router.register("informatiecategorieen", InformationCategoryViewSet)
 router.register("organisaties", OrganisationViewSet)
 router.register("publicaties", PublicationViewSet)

src/woo_publications/publications/api/filters.py

@@ -2,7 +2,32 @@
 
 from django_filters.rest_framework import FilterSet, filters
 
-from ..models import Publication
+from ..models import Document, Publication
+
+
+class DocumentFilterSet(FilterSet):
+    publication = filters.UUIDFilter(
+        field_name="publication__uuid",
+        lookup_expr="exact",
+        help_text=_(
+            "Search the document based on the unique identifier that represents a publication.."
+        ),
+    )
+    sorteer = filters.OrderingFilter(
+        help_text=_("Order on."),
+        fields=(
+            "creatiedatum",
+            "officiele_titel",
+            "verkorte_titel",
+        ),
+    )
+
+    class Meta:
+        model = Document
+        fields = (
+            "publication",
+            "sorteer",
+        )
 
 
 class PublicationFilterSet(FilterSet):

src/woo_publications/publications/api/serializer.py

@@ -1,6 +1,23 @@
 from rest_framework import serializers
 
-from ..models import Publication
+from ..models import Document, Publication
+
+
+class DocumentSerializer(serializers.ModelSerializer):
+    class Meta:  # type: ignore
+        model = Document
+        fields = (
+            "identifier",
+            "publicatie",
+            "officiele_titel",
+            "verkorte_titel",
+            "omschrijving",
+            "creatiedatum",
+            "bestandsformaat",
+            "bestandsnaam",
+            "bestandsomvang",
+            "registratiedatum",
+        )
 
 
 class PublicationSerializer(serializers.ModelSerializer):

src/woo_publications/publications/api/viewsets.py

@@ -5,9 +5,27 @@
 
 from woo_publications.logging.service import AuditTrailViewSetMixin
 
-from ..models import Publication
-from .filters import PublicationFilterSet
-from .serializer import PublicationSerializer
+from ..models import Document, Publication
+from .filters import DocumentFilterSet, PublicationFilterSet
+from .serializer import DocumentSerializer, PublicationSerializer
+
+
+@extend_schema(tags=["Documenten"])
+@extend_schema_view(
+    list=extend_schema(
+        summary=_("All available documents."),
+        description=_("Returns a paginated result list of existing documents."),
+    ),
+    retrieve=extend_schema(
+        summary=_("Retrieve a specific document."),
+        description=_("Retrieve a specific document."),
+    ),
+)
+class DocumentViewSet(AuditTrailViewSetMixin, viewsets.ReadOnlyModelViewSet):
+    queryset = Document.objects.order_by("-creatiedatum")
+    serializer_class = DocumentSerializer
+    filterset_class = DocumentFilterSet
+    lookup_field = "identifier"
 
 
 @extend_schema(tags=["Publicaties"])