From d52a697d9ed6791f3320434741c9163678b8d5ab Mon Sep 17 00:00:00 2001 From: Petter Reinholdtsen Date: Mon, 6 Mar 2023 20:28:11 +0100 Subject: [PATCH 1/3] =?UTF-8?q?Endre=20opplastingsprosedyre=20til=20=C3=A5?= =?UTF-8?q?=20unng=C3=A5=20ufullstendige=20dokumentobjekt-instanser?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Tillat opplasting direkte fra dokumentbeskrivelse og dokumentobjekt. Dette lager 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. Dette forslaget er basert på ideer i mangelmelding #25, og Reduserer utfordringer omtalt i mangelmelding #285. --- kapitler/06-konsepter_og_prinsipper.rst | 84 +++++++++++++++---- .../07-tjenester_og_informasjonsmodell.rst | 8 ++ 2 files changed, 77 insertions(+), 15 deletions(-) diff --git a/kapitler/06-konsepter_og_prinsipper.rst b/kapitler/06-konsepter_og_prinsipper.rst index d4691ac..cd2338a 100644 --- a/kapitler/06-konsepter_og_prinsipper.rst +++ b/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,14 +1342,58 @@ satt, og ikke inneholder enten «\ */*\ » eller er stemmer med verdien i mimeType-feltet til tilhørende dokumentobjekt, så returneres resultatkoden 406, ikke resultatkode 200. -**Overføre små filer** +**Opplasting** -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. +Opplasting av dokumentfiler kan enten gjøres fra dokumentbeskrivelse +eller dokumentobjekt. Resultatet fra en vellykket opplasting +returnerer JSON for det nyopprettede eller oppdaterte +dokumentobjektet. + +Eksempel på oppretting fra dokumentbeskrivelse:: -Et dokumentobjekt opprettes før opplasting. Hvis noen av feltene + 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/" + } + } + } + +Et dokumentobjekt også kan opprettes før opplasting når en laster opp +fil via dokumentobjekcts 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 @@ -1359,15 +1403,23 @@ 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 +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-entiteten, det vil +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. + + :: POST https://n5.example.com/api/arkivstruktur/Dokumentobjekt/a895c8ed-c15a-43f6-86de-86a626433785/referanseFil @@ -1412,19 +1464,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 +1543,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/" } } } diff --git a/kapitler/07-tjenester_og_informasjonsmodell.rst b/kapitler/07-tjenester_og_informasjonsmodell.rst index 84bd77e..16068d7 100644 --- a/kapitler/07-tjenester_og_informasjonsmodell.rst +++ b/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/ From d28e2efdbb66d6f1f3e79d18270f377b90c01434 Mon Sep 17 00:00:00 2001 From: Petter Reinholdtsen Date: Tue, 30 May 2023 13:08:20 +0200 Subject: [PATCH 2/3] Specify defaul value of variantformat during uploads. --- kapitler/06-konsepter_og_prinsipper.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/kapitler/06-konsepter_og_prinsipper.rst b/kapitler/06-konsepter_og_prinsipper.rst index cd2338a..d47e936 100644 --- a/kapitler/06-konsepter_og_prinsipper.rst +++ b/kapitler/06-konsepter_og_prinsipper.rst @@ -1392,6 +1392,11 @@ Eksempel på oppretting fra dokumentbeskrivelse:: } } +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. + Et dokumentobjekt også kan opprettes før opplasting når en laster opp fil via dokumentobjekcts opplastingsrelasjon. Hvis noen av feltene «format», «mimeType», «filnavn», «sjekksum», «sjekksumAlgoritme» og From 655338bc14107e6900cf14f8cba4f57fb1cf6723 Mon Sep 17 00:00:00 2001 From: Petter Reinholdtsen Date: Tue, 30 May 2023 13:18:43 +0200 Subject: [PATCH 3/3] =?UTF-8?q?Gj=C3=B8r=20det=20klarere=20at=20klienten?= =?UTF-8?q?=20kan=20velge=20opplastingsmetode,=20tjener=20m=C3=A5=20st?= =?UTF-8?q?=C3=B8tte=20begge.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- kapitler/06-konsepter_og_prinsipper.rst | 45 ++++++++++++------------- 1 file changed, 22 insertions(+), 23 deletions(-) diff --git a/kapitler/06-konsepter_og_prinsipper.rst b/kapitler/06-konsepter_og_prinsipper.rst index d47e936..d249219 100644 --- a/kapitler/06-konsepter_og_prinsipper.rst +++ b/kapitler/06-konsepter_og_prinsipper.rst @@ -1344,10 +1344,9 @@ resultatkoden 406, ikke resultatkode 200. **Opplasting** -Opplasting av dokumentfiler kan enten gjøres fra dokumentbeskrivelse -eller dokumentobjekt. Resultatet fra en vellykket opplasting -returnerer JSON for det nyopprettede eller oppdaterte -dokumentobjektet. +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:: @@ -1397,25 +1396,25 @@ dokumentobjekt-instansen opprettes automatisk ved filopplasting, med mindre API-tjenesten kjenner igjen filinnholdet som et av de godkjente arkivformatene. -Et dokumentobjekt også kan opprettes før opplasting når en laster opp -fil via dokumentobjekcts 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. +Ved opplasting fra dokumentobjekt må dokumentobjektet opprettes før en +laster opp fil via dokumentobjekcts 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**