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 å initiere 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 sending av 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} utfører sletting av en opplastetfil. Statuskode 204 indikerer at vedlegget ble slettet. Statuskode 404 tilsier at vedlegget ikke finnes, og alt kan være slettet (eller aldri vært lastet opp).

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.

Laste ned deler av en fil

StartByte og EndByte kan frivillig legges til i query for å definere en mindre bit av filen man vil laste ned. Hvis EndByte er større en størrelsen (Content-length) på filen så vil den hente resten av filen.

Standard verdi for StartByte er 0 som tilsvarer starten av filen. Standard verdi for EndByte er int64.Max som i praksis tilsvarer slutten av filen.

Kvittere på nedlastet fil

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

Sjekke nedlastingsstatus

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

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

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