Flyt

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",
  "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
  }
}