Endre opplastingsprosedyre til å unngå ufullstendige dokumentobjekt-i…

…nstanser

Tillat opplasting direkte fra dokumentbeskrivelse og dokumentobjekt.

Dette gir klienter et alternativ til dagens opplastingsprosedyre, som har
et mellomsteg der arkivet er i en ufullstendig tilstand, mellom
oppretting av dokumentobjekt-instans og vellykket opplasting av
arkivfil, og kunne laste opp fil direkte fra dokumentbeskrivelse
i tillegg til fra dokumentobjekt.  Når dokumentobjekt opprettes
automatisk brukes variantformat Produksjonsformat med mindre
API-tjenesten kjenner igjen et arkivformat.

Dette forslaget er basert på ideer i mangelmelding #25, og
Reduserer utfordringer omtalt i mangelmelding #285.

kapitler/06-konsepter_og_prinsipper.rst

@@ -1333,7 +1333,7 @@ GET https://n5.example.com/api/arkivstruktur/Dokumentobjekt/a895c8ed-c15a-43f6-8
 Returnerer med Content-type=filens MIME-type, for eksempel
 «application/pdf», og filen streames til klient. Hodefeltet
 Content-type settes til filens MIME-type hentet fra
-dokumentobjekt-entiteten. Merk, GET-forespørselen bør ikke inneholde
+dokumentobjekt-instansen. Merk, GET-forespørselen bør ikke inneholde
 HTTPs Accept-hodefelt, alternativt bør akseptere enhver MIME-type.
 HTTP-hodefeltet Accept brukes til å gi beskjed hvilket helst format
 som ønskes lastet ned, og klienten har ikke noe valg av format og bør
@@ -1342,31 +1342,87 @@ satt, og ikke inneholder enten «\ */*\ » eller er stemmer med verdien i
 mimeType-feltet til tilhørende dokumentobjekt, så returneres
 resultatkoden 406, ikke resultatkode 200.
 
+**Opplasting**
+
+Opplasting av dokumentfiler skal støttes fra både dokumentbeskrivelse
+og dokumentobjekt.  Resultatet fra en vellykket opplasting returnerer
+JSON for det nyopprettede eller oppdaterte dokumentobjektet.
+
+Eksempel på oppretting fra dokumentbeskrivelse::
+
+   POST https://n5.example.com/api/arkivstruktur/Dokumentbeskrivelse/0003f272-918a-444d-9db0-f76f8b2cb4a7/fil
+   Content-Type: image/jpeg
+   Content-Length: 2000000
+
+   JPEG data
+
+   Respons: 201 Created
+
+    {
+        "systemID": "e37be679-f87b-4485-a680-4c3e3c529bdf",
+        "versjonsnummer": "1",
+        "variantformat": {
+            "kode": "A",
+            "kodenavn": "Arkivformat"
+        },
+        "format": {
+            "kode": "RA-JPEG",
+            "kodenavn": "JPEG (ISO 10918-1:1994)"
+        },
+        "filnavn": "portrait.jpeg",
+        "filstoerrelse": 2000000,
+        "mimeType": "image/jpeg",
+        "sjekksum": "40cbd5b88175e268ef3a1c286ad7d46ff69c22787d368e8635cae7edca4b5625",
+        "sjekksumAlgoritme": "SHA-256",
+        "referanseDokumentfil": "https://n5.example.com/api/arkivstruktur/Dokumentobjekt/e37be679-f87b-4485-a680-4c3e3c529bdf/referanseFil",
+        "_links": {
+            "self": {
+                "href": "https://n5.example.com/api/arkivstruktur/Dokumentobjekt/e37be679-f87b-4485-a680-4c3e3c529bdf"
+            },
+            "https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/dokumentobjekt/": {
+                "href": "https://n5.example.com/api/arkivstruktur/Dokumentobjekt/e37be679-f87b-4485-a680-4c3e3c529bdf"
+            },
+            "https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/fil/": {
+                "href": "https://n5.example.com/api/arkivstruktur/Dokumentobjekt/e37be679-f87b-4485-a680-4c3e3c529bdf/referanseFil"
+            },
+            "https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/dokumentbeskrivelse/":{
+                "href":"https://n5.example.com/api/arkivstruktur/Dokumentbeskrivelse/0003f272-918a-444d-9db0-f76f8b2cb4a7/"
+            }
+        }
+    }
+
+Verdien for «variantformat» settes til «Produksjonsformat» når
+dokumentobjekt-instansen opprettes automatisk ved filopplasting, med
+mindre API-tjenesten kjenner igjen filinnholdet som et av de godkjente
+arkivformatene.
+
+Ved opplasting fra dokumentobjekt må dokumentobjektet opprettes før en
+laster opp fil via dokumentobjekts opplastingsrelasjon.  Hvis noen av
+feltene «format», «mimeType», «filnavn», «sjekksum»,
+«sjekksumAlgoritme» og «filstoerrelse» er fylt inn ved opprettelsen
+skal tjeneren verifisere at verdiene i de angitte feltene stemmer når
+den komplette filen er lastet opp. Tjeneren sjekker ved opplasting for
+felt som er forhåndsutfylt også at mimeType er identisk med
+Content-Type, filstoerrelse er identisk med Content-Length (for
+komplett POST) eller X-Upload-Content-Length (for overføring i bolker
+med PUT) og at sjekksum stemmer overens med den overførte filen. Hvis
+tjeneren etter opplasting ser at noen av verdiene avledet fra
+opplastet fil ikke stemmer overens med verdiene i
+dokumentobjekt-instansen, så returneres statuskode 400 Bad
+Request. Hvis den opplastede filen har et format tjeneren ikke kjenner
+igjen, så settes formatkoden til 'av/0'. Når filopplasting er fullført
+setter tjeneren de feltene i dokumentobjekt som ikke var satt ved
+oppretting av dokumentobjekt-instansen, det vil si utleder «format»,
+«mimeType», «filnavn», «sjekksum», og «filstoerrelse» basert på filens
+innhold samt, samt gir «sjekksumAlgoritme» aktuell verdi.
+
 **Overføre små filer**
 
 For å overføre en ny fil brukes POST til href til
 rel="https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/fil/" med headere for
 content-type og content-length. Når overføringen er fullført og
 filopplastingen vellykket, så returneres statuskode 201.
 
-Et dokumentobjekt opprettes før opplasting. Hvis noen av feltene
-«format», «mimeType», «filnavn», «sjekksum», «sjekksumAlgoritme» og
-«filstoerrelse» er fylt inn ved opprettelsen skal tjeneren verifisere
-at verdiene i de angitte feltene stemmer når den komplette filen er
-lastet opp. Tjeneren sjekker ved opplasting for felt som er
-forhåndsutfylt også at mimeType er identisk med Content-Type,
-filstoerrelse er identisk med Content-Length (for komplett POST) eller
-X-Upload-Content-Length (for overføring i bolker med PUT) og at
-sjekksum stemmer overens med den overførte filen. Hvis tjeneren etter
-opplasting ser at noen av verdiene avledet fra opplastet fil ikke
-stemmer overens med verdiene i dokumentobjekt-entiteten, så returneres
-statuskode 400 Bad Request. Hvis den opplastede filen har et format
-tjeneren ikke kjenner igjen, så settes formatkoden til 'av/0'. Når
-filopplasting er fullført setter tjeneren de feltene i dokumentobjekt
-som ikke var satt ved oppretting av dokumentobjekt-entiteten, det vil
-si utleder «format», «mimeType», «filnavn», «sjekksum», og
-«filstoerrelse» basert på filens innhold samt, samt gir
-«sjekksumAlgoritme» aktuell verdi.
 
 ::
 
@@ -1412,19 +1468,18 @@ For å starte en opplastingssesjon:
 #. Når siste overføring er gjort så returneres statuskode 201 Created.
 
 Det er ikke mulig å overskrive filen tilhørende en eksisterende
-dokumentobjekt-entitet med en POST eller en PUT-forespørsel. Hvis en
+dokumentobjekt-instans med en POST eller en PUT-forespørsel. Hvis en
 fil må erstattes etter fullført opplasting så skal
 dokumentobjekt-entieten slettes og en ny POST/PUT utføres mot href til
 rel=\ https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/fil/.
 
-Når en filopplasting er vellykket, så returneres tilhørende
-dokumentobjekt som respons på avsluttende 200 OK / 201 Created.
+Når en filopplasting er vellykket, så returneres tilhørende instanser
+som respons på avsluttende 200 OK / 201 Created.
 
 Dersom det skjer en feil under opplasting eller lagringsprosessen skal
 tjeneren returnere 422 Unprocessable Entity som svar. Det er da
-klientens ansvar å slette relaterte dokumentbeskrivelse- og
-dokumentobjekt-entiteter ved hjelp av DELETE på entitetenes
-self-relasjon.
+klientens ansvar å slette relaterte ikke lenger relevante instanser
+ved hjelp av DELETE på instansenes self-relasjon.
 
 Komplett eksempel
 
@@ -1492,6 +1547,9 @@ Last opp siste del:
            },
            "https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/fil/": {
                "href": "https://n5.example.com/api/arkivstruktur/Dokumentobjekt/e37be679-f87b-4485-a680-4c3e3c529bdf/referanseFil"
+           },
+           "https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/dokumentbeskrivelse/":{
+               "href":"https://n5.example.com/api/arkivstruktur/Dokumentbeskrivelse/9ee41886-bc55-11ed-9ca7-e7af3ac784aa/"
            }
        }
    }

kapitler/07-tjenester_og_informasjonsmodell.rst

@@ -1488,6 +1488,13 @@ begrepet enkeltdokument. En registrering som dokumenterer en
 transaksjon, vil vanligvis bestå av bare ett enkeltdokument.
 Dokumentbeskrivelsen inneholder altså metadata for enkeltdokumenter.
 
+Ved opplasting av fil ved bruk av relasjonen
+https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/fil/ , så vil
+det automatisk opprettes et dokumentobjekt med forvalgte verdier
+avledet fra den opplastede filen, se kapittel 6.  JSON for dette
+objektet returneres som resultat av opplastingen, på eneste
+forespørslen for små filer og på siste forespørsel for store filer.
+
 .. list-table:: Relasjoner
    :widths: 4 5 4 4
    :header-rows: 1
@@ -1524,6 +1531,7 @@ Dokumentbeskrivelsen inneholder altså metadata for enkeltdokumenter.
  * - self
  * - https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/dokumentbeskrivelse/
  * - https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/dokumentobjekt/
+ * - https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/fil/
  * - https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/merknad/
  * - https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/ny-dokumentbeskrivelse/
  * - https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/ny-dokumentobjekt/