diff --git a/kapitler/06-konsepter_og_prinsipper.rst b/kapitler/06-konsepter_og_prinsipper.rst index d4691ac..d249219 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,6 +1342,80 @@ 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 @@ -1349,24 +1423,6 @@ rel="https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/fil/" med headere fo 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/" } } } 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/