ODRC: Publicatie & Document API resources

[RutgerICATT]

Als architect wil ik via API's publicaties met documenten kunnen opslaan en ontsluiten, zodat we hierbovenop interactiecomponenten (ODPC en ODBP) kunnen ontwikkelen.

Description (why)
uit PSA: Bovenop die opslag kunnen de eerste API’s gerealiseerd worden. Het kunnen creëren, raadplegen,
muteren en verwijderen van publicaties ligt voor de hand. Wanneer bij het inrichten van de data
opslag al rekening is gehouden worden met toekomstige epics, kan dat ook al hier. Bij het
realiseren van de API’s kan ook gelijk geborgd worden dat de logging wordt gevuld.

Acceptance criteria (what)

---

Publicatie: moved to #35

---

Document: broken up into #37, #38 and #19

• Via een API kan een document (data-object) gecreëerd, geraadpleegd, gemuteerd en verwijderd worden.
• Bij een document moet exact één bestand (bijvoorbeeld een PDF) worden opgeslagen.
• Een document moet aan exact één publicatie gerelateerd worden.
  • Een publicatie kan aan geen, een of meer documenten gerelateerd zijn.
• Minimaal worden bij een document de volgende gegevens vastgelegd: identifier, officieleTitel, verkorteTitel, omschrijving, format, creatiedatum
  • Attribuutnamen zijn niet heilig, maar voor de herkenbaarheid hanteer ik gemakshalve de DiWoo-termen
  • DiWoo ondersteunt het toekennen van meerdere identifiers, titels en omschrijvingen. Voor nu is het voldoende als we voor deze velden één waarde kunnen opslaan.
  • Het format wordt automatisch herkend (dus niet aangeleverd in de API-call).
• Het is zowel mogelijk:
  • om één document te raadplegen (op basis van de identifier),
  • om een lijst (array) van documenten op te vragen ,
  • om een lijst (array van alle documenten behorende bij één publicatie op te vragen,
  • Bij het opvragen van een lijst kan sortering en pagination toegepast worden.
• De creatie, mutatie of verwijdering van een document wordt gelogd (zie ODRC: Set up foundation for logging/audit trails #16 )
• Optioneel: de raadpleging van een of meerdere documenten wordt gelogd (zie ODRC: Set up foundation for logging/audit trails #16 ). Graag laten weten of dit wordt meegenomen!
• De API specificatie is bijgewerkt (ReDoc, Swagger)
• De documentatie is bijgewerkt (Read the Docs)
• Een grafisch datamodel van de database is beschikbaar / bijgewerkt (op GitHub of Read the Docs of elders)

---

Specific details (how)

Test plan

Tasks

• ODRC: Publicatie resource #35

• ODRC: Add filter parameters to Publicatie list endpoint #68

• Expose owner/creator of Publicatie and allow filtering #69

• ODRC: Add Document data model #37

• ODRC: expose READ operations for Document resource #38

• ODRC: implement Document creation/upload #19

• Additional metadata (TODO/more refinement needed)

  • ODRC: Nieuw attribuut "status" #33
  • Creator identifier/display name -> should be taken from related audit log records (? check performance impact)
  • Add relation organization (required), which is the publishing organization
  • Add relation organisatie_onderdeel (optional), which must be an OO (ODRC: Toevoegen andere organisaties en organisatieonderdelen #8) within the selected organization
  • Add relation informatiecategorie, see ODRC: implement informatiecategorie resource #14 - assumption: this kind of metadata is the same for all documents inside publication
  • Add relation thema, see ODRC: Toevoegen themas #11 - assumption: this kind of metadata is the same for all documents inside publication
  • Publicatie list endpoint filter params (creator identifier, status, information category, theme, organization, OO)

• Additional Document metadata

  • Add fields documenthandeling, documentsoort, geldigheid

• Optimize list API endpoint /api/v1/documenten for Sitemap generation (TODO: refine)

  • List endpoint accepts filter parameter on verantwoordelijke, informatiecategorie, publicatie__created_on
  • List endpoint must accept a filter parameter origin=waardelijst which filters out documents with a informatiecategorie/organisatie with origin zelf_toegevoegd. This is to ensure that we only retrieve data that can be indexed in the national index, to build the sitemaps.

• Update publicatie resource to emit nested documenten resource (no URL references, expand them directly)

[sergei-maertens]

Considerations for estimate (5-10 work days)

• Resource Publication, supports CRUD. Requires some authn/authz logic:

  • READ (list, detail): must be authenticated, permissions to allow/deny draft publications (ODPC requires drafts, ODBP only allows non-draft)
  • CREATE, UPDATE, DELETE: must be authenticated, must have write permissions

• Resource Document, supports CRUD to create the metadata + the upload/download of binary data

  • READ: if the document is not published yet, requires appropriate draft permissions (i.e. ODBP should not get access to documents at all if the document is not part of a non-draft publication)
  • CREATE, UPDATE, DELETE: requires write permissions
  • Uploading of binary data: would be best to have the actual file upload as multipart/form-data instead of JSON + base64 encoding, as the latter has about 33% overhead. A PUT call to the created document purely dedicated for the upload is probably simplest.
  • Downloading of the binary data: needs to be a django-sendfile2/django-privates response so that the webserver (nginx) does the actual serving of the files, but have the API check the permissions. For draft publications (or lack of publication), downloads should be restricted to authenticated clients with write permissions (i.e. the ODPC), for published documents, either require authentication for the ODBP or even make it a public endpoint (to potentially save on network hops/proxies).

• Writing up the above about permissions: instead of read/write permissions, maybe it makes more sense to identify two roles: odpc and odbp mapping to the PSA diagram, and the roles can be added to the API keys.

• API endpoints must support custom request headers for audit trails: Audit-User-Representation, Audit-User-ID, Audit-Remarks. ODPC/ODBP are responsible for populating these.

[sergei-maertens]

Initial pass for the API resource, which is going to be wildly incomplete, but it's a starting point for something that is useful for the publication component/burger portaal

Publicatie:
  type: object
  properties:
    uuid:
      type: string
      format: uuid
    name:
      type: string
    status:
      type: string
      enum:
        - draft
        - published
        - retracted
    documenten:
      type: array
      minItems: 0
      items: 
        $ref: '#/Document'
    createdOn:
      type: string
      format: date-time
    creator:
      type: object
      properties:
        displayName:
          type: string
        identifier:
          type: string


Document:
  type: object
  properties:
    uitgever:
      $ref: '#/OrganisatieReference'
    verantwoordelijke:
      $ref: '#/OrganisatieReference'
    titel:
      type: string
    informatiecategorie:
      type: object
      properties:
        name:
          type: string
        identifier:
          type: string
          format: uri
        origin:
          type: string
          enum:
            - waardelijst
            - zelf_toegevoegd
    creatiedatum:
      type: string
      format: date
    documenthandeling:
      type: object
      properties:
        soortHandeling:
          type: string
          enum:  # uit waardelijst
            - foo
            - bar
        tijdstip:
          type: string
          format: date-time
    documentsoort:
      type: object
      properties:
        name:
          type: string
        identifier:  # uit waardelijst
          type: string
          format: uri
    thema:
      type: object
      properties:
        name:
          type: string
        identifier:  # uit waardelijst
          type: string
          format: uri
    geldigheid:
      type: object
      properties:
        begin:
          type: string
          format: date
        eind:
          type: string
          format: date
    downloadUrl:  # read-only
      type: string
      format: uri

OrganisatieReference:
  type: object
  properties:
    name:
      type: string
    identifier:
      type: string
      format: uri

[sergei-maertens]

Estimate still at 5-10 days

[MarcoKlerks]

@sergei-maertens Ik heb het kopje "acceptatiecriteria" ingevuld. Kun je hier eens naar kijken en er feedback op geven?

• Ik heb alvast een splitsing aangebracht tussen de criteria voor publicaties en de criteria voor documenten. Ik hoop dat dit helpt om de story te splitsen in twee kleinere stories.
• Ik heb wat strakker afgebakend welke attributen nu al opgenomen moeten worden. Andere attributen kunnen we later toevoegen. Ik hoop dat dit helpt om de "t-shirt maat" kleiner te maken.
• Ik heb expliciet wat criteria opgenomen inzake de documentatie. De documentatie is belangrijk voor mijn achterban.
• Helpt dit? Is het te veel detail-geneuzel of juist te weinig? Mis je iets of is iets niet duidelijk genoeg?

[sergei-maertens]

See: GPP-Woo/GPP-app#34 for part of the UI work

[MarcoKlerks]

creatiedatum doen we alleen op document-niveau en niet op publicatie-niveau. Dit n.a.v. discussie op Slack. Ik heb dit aangepast in de acceptatie criteria.