Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Endre opplastingsprosedyre til å unngå ufullstendige dokumentobjekt-instanser #298

Merged
merged 3 commits into from
May 30, 2023
Merged

Endre opplastingsprosedyre til å unngå ufullstendige dokumentobjekt-instanser #298

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
d52a697
Endre opplastingsprosedyre til å unngå ufullstendige dokumentobjekt-i…
petterreinholdtsen Mar 6, 2023
d28e2ef
Specify defaul value of variantformat during uploads.
petterreinholdtsen May 30, 2023
655338b
Gjør det klarere at klienten kan velge opplastingsmetode, tjener må s…
petterreinholdtsen May 30, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
108 changes: 83 additions & 25 deletions kapitler/06-konsepter_og_prinsipper.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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 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**

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.

::

Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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/"
}
}
}
Expand Down
8 changes: 8 additions & 0 deletions kapitler/07-tjenester_og_informasjonsmodell.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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/
Expand Down