From 7d4d5485b9766e85ce63a3e6f8921686f17567ef Mon Sep 17 00:00:00 2001 From: Petter Reinholdtsen Date: Tue, 22 Aug 2023 12:36:06 +0200 Subject: [PATCH] Extend and explain in more details how to upload large files. Introduce new bulkgrense system value to allow clients to learn exactly how small small files are. Specify how to reject large files using the small method. Explain the format of Range and Content-Range headers. Made it clear that the upload need to be done in sequence (and not out of order) by specifying that the Location header returned after each bulk upload is to be used in the next bulk upload. Drop the Google Drive reference. It do not really explain much, the URL is broken and this specification should describe its own protocol as it is not identical to the Google Drive protocol. Fixes #313. --- kapitler/06-konsepter_og_prinsipper.rst | 85 +++++++++++++++++++------ 1 file changed, 65 insertions(+), 20 deletions(-) diff --git a/kapitler/06-konsepter_og_prinsipper.rst b/kapitler/06-konsepter_og_prinsipper.rst index 0fd6256..442daee 100644 --- a/kapitler/06-konsepter_og_prinsipper.rst +++ b/kapitler/06-konsepter_og_prinsipper.rst @@ -173,6 +173,10 @@ Når en tar GET mot href for relasjonsnøkkelen https://rel.arkivverket.no/noark5/v5/api/admin/system/, så får en informasjon om API-tjenersystemet. Responsen inneholder følgende felter: +- ``bulkgrense`` - positivt heltall med øvre grense for hva som anses + som små opplastinger i bytes. Hvis feltet mangler skal det antas å + være 157286400 (150 MiB). Hvis verdien er 0 er det ingen øvre + grense. - ``leverandoer`` - tekststreng med navn på leverandør av tjenestegrensesnittimplementasjonen. - ``produkt`` - tekststreng med navn på produktet som leverer @@ -189,6 +193,7 @@ Responsen kan for eksempel se slik ut: .. code:: python { + "bulkgrense": 1073741824, "leverandoer": "Hoffleverandøren", "produkt": "Arkivsystemet Noark 5 kjerne", "versjon": "0.1", @@ -1435,16 +1440,21 @@ fullført og filopplastingen vellykket, så returneres statuskode 201. Respons: 201 Created +Hvis tjeneren anser filstørrelsen som for stor til å overføræs som en +liten fil, så skal den returnere statuskode 403 (Forbidden) for å +signalere at klienten må bruke metoden for overføring av store filer. +Grensen for hva som anses som små filer kan hentes fra endepunktet bak +relasjonsnøkkelen +https://rel.arkivverket.no/noark5/v5/api/admin/system/ i verdien +``bulkgrense``. + **Overføre store filer** -For store filer (over 150MB) så kan filen overføres i -bolker. Prosessen for å overføre store filer er inspirert av APIet til -Google Drive, -https://developers.google.com/drive/v3/web/resumable-upload . For -hver bolk returneres statuskode 200, unntatt den siste når -overføringen er fullført der det returneres statuskode 201. +For store filer så kan filen overføres i bolker. For hver bolk +returneres statuskode 200, unntatt den siste når overføringen er +fullført der det returneres statuskode 201. -For å starte en opplastingssesjon: +For å starte en opplastingsøkten: #. Send en POST til href til relasjonsnøkkel «https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/fil/». @@ -1455,16 +1465,22 @@ For å starte en opplastingssesjon: Headeren X-Upload-Content-Length settes til filens totalstørrelse -#. Responsen du mottar vil inneholde en Location-Header som inneholder - en sesjons-URI som skal benyttes i en PUT-forespørsel for å overføre - filen i bolker. +#. Responsen du mottar vil inneholde et Location-hodefelt som + inneholder en økt-URI som skal benyttes i neste PUT-forespørsel for + å overføre neste bolk av filen. På samme måte som med href kan + Location-hodefeltet returnert fra tjeneren inneholde hva som helst. #. Deretter overføres filen med en PUT-forespørsel. Responsen fra - serveren inneholder en Range-header, hvor øvre verdi pluss en - benyttes som start verdi i Content-Range i neste oversending. + serveren inneholder en Range-header på formen "Range: + -<øvre>", hvor øvre verdi pluss en benyttes som nedre verdi + i Content-Range i overføring av neste bulk. Responsen inneholder + et Location-hodefelt som brukes i neste PUT-forespørsel. - Headeren Content-Range settes for å angi hvor mye av filen som - blir oversendt. + Headeren Content-Range settes for å angi hvor mye av filen som blir + oversendt, på formen "Content-Range: + -<øvre>/". Headeren Content-Length skal + inneholde antall bytes som overføres, dvs. <øvre> minus + pluss 1. #. Når siste overføring er gjort så returneres statuskode 201 Created. @@ -1482,9 +1498,10 @@ tjeneren returnere 422 Unprocessable Entity som svar. Det er da klientens ansvar å slette relaterte ikke lenger relevante instanser ved hjelp av DELETE på instansenes self-relasjon. -Komplett eksempel +Her er et komplett eksempel, med opplasting av 200000 byte i 512 +KiB-bulker. -Opprett sesjon: +Opprett økten: :: @@ -1495,27 +1512,55 @@ Opprett sesjon: Respons: 200 OK - Location: https://n5.example.com/api/arkivstruktur/Dokumentobjekt/a895c8ed-c15a-43f6-86de-86a626433785/referanseFil?filsesjon=abc1234567 + Location: https://n5.example.com/api/arkivstruktur/Dokumentobjekt/a895c8ed-c15a-43f6-86de-86a626433785/referanseFil?ref=abc1234567-1 Last opp første del: :: - PUT https://n5.example.com/api/arkivstruktur/Dokumentobjekt/a895c8ed-c15a-43f6-86de-86a626433785/referanseFil?filsesjon=abc1234567 + PUT https://n5.example.com/api/arkivstruktur/Dokumentobjekt/a895c8ed-c15a-43f6-86de-86a626433785/referanseFil?ref=abc1234567-1 Content-Length: 524288 Content-Type: image/jpeg Content-Range: bytes 0-524287/2000000 Respons: 200 OK - Location: https://n5.example.com/api/arkivstruktur/Dokumentobjekt/a895c8ed-c15a-43f6-86de-86a626433785/referanseFil?filsesjon=abc1234567 + Location: https://n5.example.com/api/arkivstruktur/Dokumentobjekt/a895c8ed-c15a-43f6-86de-86a626433785/referanseFil?ref=abc1234567-2 Range: bytes 0-524287 +Last opp andre del: + +:: + + PUT https://n5.example.com/api/arkivstruktur/Dokumentobjekt/a895c8ed-c15a-43f6-86de-86a626433785/referanseFil?ref=abc1234567-2 + Content-Length: 524288 + Content-Type: image/jpeg + Content-Range: bytes 524288-1048575/2000000 + + Respons: 200 OK + + Location: https://n5.example.com/api/arkivstruktur/Dokumentobjekt/a895c8ed-c15a-43f6-86de-86a626433785/referanseFil?ref=abc1234567-3 + Range: bytes 0-1048575 + +Last opp tredje del: + +:: + + PUT https://n5.example.com/api/arkivstruktur/Dokumentobjekt/a895c8ed-c15a-43f6-86de-86a626433785/referanseFil?ref=abc1234567-3 + Content-Length: 524288 + Content-Type: image/jpeg + Content-Range: bytes 1048576-1572863/2000000 + + Respons: 200 OK + + Location: https://n5.example.com/api/arkivstruktur/Dokumentobjekt/a895c8ed-c15a-43f6-86de-86a626433785/referanseFil?ref=abc1234567-4 + Range: bytes 0-1572863 + Last opp siste del: :: - PUT https://n5.example.com/api/arkivstruktur/Dokumentobjekt/a895c8ed-c15a-43f6-86de-86a626433785/referanseFil?filsesjon=abc1234567 + PUT https://n5.example.com/api/arkivstruktur/Dokumentobjekt/a895c8ed-c15a-43f6-86de-86a626433785/referanseFil?ref=abc1234567-4 Content-Length: 427136 Content-Type: image/jpeg Content-Range: bytes 1572864-1999999/2000000