Store filer / DEFT (Direkte og Enkel FilTransportør)

Overordnet

Under er listen over endepunktene:

For opplasting velger man en av to metoder. Én hel fil med POST /objects, eller en fil oppstykket i flere små filer (multipart). Sistnevnte gjennomføres ved å initialisere opplastingen med POST /objects/initialization som returnerer en key. Denne brukes når en fortsetter med POST /objects/{key}/part hvor hver bit av det oppstykkede vedlegget lastes opp. Til slutt POST /objects/{key}/completion, alternativt POST /objects/{key}/cancellation.

Returverdien fra en opplastet fil er en lenke som kan brukes til å laste ned filen. Denne kan sendes mottaker via en annen kommunikasjonskanal, eller f.eks. brukes som en fil-referanse i en fagmelding. Filreferansen som returneres etter opplasting inneholder hele lenken, så filen kan f.eks. lastes ned direkte i en nettleser ved å aksessere lenken. Alternativt så kan nøkkelen (key) brukes til å laste ned filen ved å gjøre et kall mot GET /objects/{key}.

Sletting av en opplastet fil kan gjøres av avsender med DELETE /objects/{key}. Nedlaster skal også markere filen som nedlastet med PUT /objects/{key}/download-receipt/{markerHerId}. Når alle mottaker har lastet ned og markert filen som nedlastet, vil den bli automatisk slettet. Filen vil automatisk slettes av retention mekanismer noen dager etter opplasting, så REST APIet skal ikke brukes til lagring, kun transport

Opplaster kan også verifisere hvem som har kvittert på nedlasting med GET /objects/{key}/download-status

Helhetlig flyt

Opplasting

Opplastning av filer kan gjøres på to måter: Ved å laste opp hele filen med en gang, eller ved å dele opp filen lokalt for så å laste opp hver del/"chunk" av den oppdelte filen.

Laste opp én fil sammenhengende

Førstnevnte POST /objects, bruker multipart/form-data til å laste opp en hel fil av gangen. Filen streames fra klienten og settes sammen på REST API siden. Fordelen med denne metoden er at det kun krever et API kall for å laste opp en fil, og minneforbruket på klientsiden er lavt noe som gjør det godt egnet for "tynne" brukergrensesnitt som f.eks. nettlesere. I requesten må det defineres et filnavn som en del av Content-Disposition, samt SenderHerId og ReceiverHerIds som query i requesten.

eksempel på query med 123 som avsender, og 456 og 789 som mottakere

/objects?SenderHerId=123&ReceiverHerIds=456&ReceiverHerIds=789

Laste opp én fil i flere deler

Den andre måten å laste opp et vedlegg på er å initialere en opplastning med POST /objects/initialization, laste opp hver del av filen med POST /objects/{key}/part, og fullføre opplastingen med POST /objects/{key}/completion. Denne måten å laste opp på passer best hvis man har mulighet til å dele opp filen lokalt og anbefales ved veldig store filer, eller når opplastingshastigheten er lav og man vil sikre seg mot avbrudd som kan avbryte opplastningen.

POST /objects/initialization eksempel request body:

{
  "fileName": "my-secret-passwords.txt",
  "senderHerId": 123,
  "receiverHerIds": [
    456,
    789
  ]
}

POST /objects/initialization eksempel response body:

{
  "key": "fcffff81-0bdd-4be0-81a6-777f9bd10bb3_my-secret-passwords.txt",
  "uploadId": "aGVsbG8gbXIgb3IgbXJzIGRldmVsb3BlciA6KQ=="
}

POST /objects/{key}/part eksempel request body:

{
  "uploadId": "aGVsbG8gbXIgb3IgbXJzIGRldmVsb3BlciA6KQ==",
  "file": @filepart_2,
  "partNumber": 2
}

❗️partNumber er begrenset til å være mellom 1 og 10'000. Sekvensen på partNumber bestemmer rekkefølgen på hvordan delene blir satt sammen til en hel fil, så opplasting av deler kan skje parallelt

POST /objects/{key}/part eksempel response body:

{
  "partNumber": 2,
  "eTag": "cXdlZHNhenhjdmZydA=="
}

❗️ partNumber og eTag er et key-value par som må tas vare på av opplasteren da disse brukes for å sette sammen filen helt til slutt. POST /objects/{key}/part gjøres til alle deler av fila er lastet opp.

POST /objects/{key}/completion eksempel request body:

{
  "uploadId": "aGVsbG8gbXIgb3IgbXJzIGRldmVsb3BlciA6KQ==",
  "partETags": [
    {
      "partNumber": 1,
      "eTag": "eXV0aWdraGpkeWVodA=="
    },
    {
      "partNumber": 2,
      "eTag": "cXdlZHNhenhjdmZydA=="
    },
    {
      "partNumber": 3,
      "eTag": "YWlza2RqZmhneXR1Nw=="
    }
  ]
}

POST /objects/{key}/completion eksempel respons:

Response Headers:
    location: url

Response Body:
    key

Avbryt opplasting av oppdelt fil

Skulle det være behov for å avbryte opplastningen gjøres det et kall mot POST /objects/{key}/cancellation

POST /objects/{key}/cancellation eksempel request body:

{
  "uploadId": "aGVsbG8gbXIgb3IgbXJzIGRldmVsb3BlciA6KQ=="
}

Sletting

DELETE /objects/{key} vil utføre sletting av et vedlegg som har blitt opplastet. Statuskode 204 indikerer at vedlegget ble slettet. Statuskode 404 tilsier at vedlegget ikke finnes, og kan alt være slettet (eller ikke eksistert til å begynne med)

Nedlasting

Laste ned fil

Nedlastning gjøres ved å aksessere referansen/url-en, eller med GET /objects/{key} hvis man kun har key. Location url-en som ble generert etter opplasting tilsvarer det samme som en oppbygd GET /objects/{key} request.

Kvitere på nedlastet fil

Når filen er nedlastet skal den kviteres som nedlastet. Det gjøres med en PUT /objects/{key}/download-receipt/{markerHerId} request hvor markerHerId tilsvarer HerIDen som kviterer på at filen er lastet ned

Sjekke nedlastingsstatus

Opplaster kan sjekke hvilke mottakere som har kvitert og hvilke mottakere som ikke har kvitert. Det gjøres med en GET /objects/{key}/download-status request som returnerer en json body med informasjon om kviteringsstatus.

GET /objects/{key}/download-status eksempel response body:

{
  "receiverDownloadStatus": {
    "123": true,
    "4567": false,
    "78": true
  }
}

Verdt å vite

Det er verdt å vite at filnavn på vedlegg kan maks være 100 tegn langt, og kan kun inneholde bokstavene a-å, store og små, tallene 0-9 og spesialtegnene bindestrek ( - ) og understrek ( _ ). Dette er av kompabilitet og sikkerhetsmessige årsaker. Punktum er tillat, men kun for å skille mellom filnavn og filutvidelse.