Programmeringsgrensesnitt (API)

Oversikt

Nasjonalbibliotekets tjenester for digital bevaring tilbyr REST-baserte API-er for å håndtere innlevering (submission) og utlevering (dissemination) av digitale objekter. Dette lar klienter integrere sine systemer med våre bevaringsløp.

Denne dokumentasjonen gir en overordnet oversikt over tilgjengelige API-er. For komplette tekniske detaljer, se vår Swagger UI.

Den maskinlesbare OpenAPI-spesifikasjonen (JSON) er tilgjengelig på https://api.nb.no/dps-submission/v1/api-docs.

Med API-et kan du:

• Levere materiale til bevaring: levere digitale objekter til bevaring.
• Legge til bevaringseventer: legge til bevaringseventer i en innlevering.
• Bestille utlevering av bevart materiale: bestille bevarte digitale objekter.
• Motta varsler: få automatiske statusoppdateringer i dine systemer via webhooks.

Denne siden lister også endepunkter, felt i forespørsler og statusflyt for innleveringer og utleveringer, og meldingene som sendes via webhooks.

Autentisering og autorisasjon

API-et bruker OAuth 2.0 med JWT-token for autentisering, og implementerer spesifikt OAuth 2.0 Client Credentials-flyten. Tjenestene er designet for system-til-system-kommunikasjon og støtter ikke autentiseringsflyter basert på sluttbrukere (f.eks. Authorization Code-flyt).

OAuth 2.0 Client Credentials-flyt

1. Klientapplikasjonen din autentiserer seg mot autorisasjonsserveren ved å bruke client ID og client secret.
2. Autorisasjonsserveren validerer disse legitimasjonene og returnerer et access token.
3. Applikasjonen inkluderer dette tokenet i Authorization-headeren i alle API-kall.

All API-kommunikasjon skjer via https://api.nb.no, mens autentiseringsforespørsler sendes til https://www.nb.no/authn/realms/dps/protocol/openid-connect/token.

Eksempel på token-forespørsel:

POST /authn/realms/dps/protocol/openid-connect/token HTTP/1.1
Host: www.nb.no
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id={your_client_id}
&client_secret={your_client_secret}

Eksempel på API-kall med token:

GET /dps-submission/v1/contracts/{your_contract_id}/submissions/{your_submission_id} HTTP/1.1
Host: api.nb.no
Authorization: Bearer {access_token}

Rollebasert tilgangsstyring

Tilgang til endepunkter styres gjennom roller:

• Kontraktsspesifikke roller ({contractId}_R, {contractId}_W) gir lese- og skrivetilgang til ressurser under en spesifikk kontrakt
• Rollen DPS_SUBMISSION_HANDLER kreves for interne statusoperasjoner

Klientapplikasjonen må hente access token, og den utstedte JWT-en vil inneholde tildelte roller.

Feilhåndtering

API-et bruker vanlige HTTP-statuskoder:

• 200 OK – Vellykket
• 201 Created – Ressurs opprettet
• 400 Bad Request – Feil i forespørselen
• 401 Unauthorized – Manglende eller ugyldig token
• 403 Forbidden – Token gyldig, men mangler rettigheter
• 404 Not Found – Ressurs ikke funnet
• 409 Conflict – Duplikat forespørsel
• 422 Unprocessable Entity – Ressurs finnes men er ikke bevart / ikke klar
• 500 Internal Server Error – Uventet feil
• 502 Bad Gateway – En tjeneste API-et er avhengig av, feilet

Feilresponser følger RFC 9457 Problem Details for HTTP APIs og returneres med medietypen application/problem+json:

{
  "type": "https://digitalpreservation.no/problems/submission-not-found",
  "title": "Submission Not Found",
  "status": 404,
  "detail": "Submission with ID 7mVKGHwOA6w2Ot8feF9fIU was not found",
  "instance": "/v1/contracts/4eaf/submissions/7mVKGHwOA6w2Ot8feF9fIU",
  "timestamp": "2025-10-14T10:03:00.123Z",
  "errorCategory": "NOT_FOUND"
}

Innleveringer

Endepunkter for innlevering av materiale. En trinnvis gjennomgang finnes under Levere materiale til bevaring. Alle stier er relative til https://api.nb.no/dps-submission.

Endepunkter for innlevering

• Liste over submissions: Sortert etter når de ble opprettet, og paginert med page (nullbasert, standard 0) og size (standard 10). Filtrer med objectId og/eller archiveId (eksakt treff; flere filtre kombineres med OG). Hvis ingenting treffer, er responsen en tom side.
• Hent submission: Bruk query-parameteren include for å ta med relaterte data i responsen: FILES (registrerte filer), DESCRIPTIVE_METADATA (metadataene fra forespørselen) og EVENTS (bevaringshendelser), f.eks. ?include=FILES&include=EVENTS.
• Slett submission: Bare tillatt mens submissionen har status REGISTERED og ikke har registrerte filer. Slett filene først; en submission som fortsatt har filer, gir 409 Conflict.
• Slett fil: Bare tillatt mens submissionen har status REGISTERED; ellers svarer API-et med 409 Conflict. Som standard slettes bare filregistreringen. Legg til deleteFromS3=true for også å slette den opplastede filen fra S3.
• Fullfør submission: Submissionen må ha minst én registrert fil som ikke er tom, og alle registrerte filer må ligge i S3; ellers svarer API-et med 422 Unprocessable Entity. En submission kan bare fullføres én gang; et nytt kall gir 409 Conflict.
• Send inn event: Bare tillatt mens submissionen har status REGISTERED. En vellykket forespørsel gir 204 No Content.

Felt i forespørsler om innlevering

Opprett submission

Registrer fil

Responsen inneholder fileId, s3ObjectKey og en uploadUrl for opplasting av filinnholdet.

Begrensninger for innlevering

Begrensningen i filstørrelse skyldes restriksjoner i pre-signerte S3-URL-er. Større filer kan lastes opp direkte til S3 med s3ObjectKey; dette er primært ment for intern bruk på Nasjonalbiblioteket.

Statusflyt for innlevering

En submission går gjennom følgende statuser:

1. REGISTERED – Opprettet
2. UPLOAD_COMPLETED – Alle filer er lastet opp og submission er fullført
3. PROCESSING – Innholdet overføres til, valideres og arkiveres i bevaringssystemet
4. PRESERVED – Innholdet er bevart
5. REJECTED – Submission er avvist pga. feil

Endringer til PRESERVED og REJECTED sendes også som webhook-meldinger (submission.preserved og submission.rejected).

Utleveringer

Endepunkter for å bestille utlevering av bevart materiale. En trinnvis gjennomgang finnes under Bestille utlevering av bevart materiale. Alle stier er relative til https://api.nb.no/dps-submission.

Endepunkter for utlevering

• Opprett utlevering: API-et kontrollerer at klienten er autorisert, at pakken finnes og er bevart, og at forespørselen ikke er et duplikat. Hvis en utlevering allerede pågår, svarer API-et med 409 Conflict. Forberedelsen kjører deretter i bakgrunnen, og resultatet leveres gjennom webhooken dissemination.delivered.

Felt i forespørsler om utlevering

Statusflyt for utlevering

Foreløpige statuser (kan utvides):

1. RECEIVED – Mottatt
2. QUEUED – Lagt i kø
3. DOWNLOADING_FROM_REPOSITORY – Laster ned fra repository
4. FIXITY_CHECK – Integritetskontroll
5. UPLOADING_TO_S3 – Laster opp til S3
6. DISSEMINATED – Utlevert
7. FAILED – Feilet
8. REJECTED – Avvist

Nedlastingslenkene i webhooken dissemination.delivered utløper på tidspunktet som er angitt i expirationDate. Hver nye utlevering får nye lenker.

Webhooks

Meldinger som DPS sender til webhook-endepunktet ditt. Hvordan du setter opp og verifiserer et endepunkt, er beskrevet under Motta varsler. DPS bruker Standard Webhooks for format og signering.

Levering av webhooks

Webhook-headere

Alle meldinger sendes med følgende headere:

webhook-id: <unik id>
webhook-timestamp: <unix-sekunder>
webhook-signature: v1,<base64-signatur>

Tips: verifiser alltid signaturen mot rå request-body, ikke en reserialisert JSON-struktur.

Struktur på webhook-meldinger

Alle webhook-meldinger følger samme struktur («envelope»):

{
  "type": "<event type>",
  "timestamp": "2025-09-10T00:08:11.407000+02:00",
  "data": {}
}

Webhook-hendelser

DPS støtter foreløpig følgende hendelser.

submission.preserved

Webhook sendt når en SIP-innlevering er bevart og lagret permanent.

Eksempel

{
  "type": "submission.preserved",
  "timestamp": "2025-09-10T00:08:11.407000+02:00",
  "data": {
    "contractId": "ef23",
    "submissionId": "8Z7x1T9rN0Xc2B5Yq4L3zP",
    "archiveId": "019e404e-60ab-7457-b7c9-94c453242c69"
  }
}

submission.rejected

Webhook sendt når en SIP-innlevering er avvist under validering eller behandling.

Eksempel

{
  "type": "submission.rejected",
  "timestamp": "2025-09-10T00:08:11.407000+02:00",
  "data": {
    "contractId": "ef23",
    "submissionId": "8Z7x1T9rN0Xc2B5Yq4L3zP",
    "archiveId": "019e404e-60ab-7457-b7c9-94c453242c69",
    "reasons": [
      {
        "code": "METADATA_SCHEMA_INVALID",
        "message": "Descriptive metadata did not validate against the required profile."
      },
      {
        "code": "FILE_CHECKSUM_MISMATCH",
        "message": "Checksum mismatch.",
        "filePath": "objects/issue_1942_05.pdf"
      }
    ]
  }
}

dissemination.delivered

Webhook sendt når et leveransesett (DIP) er gjort tilgjengelig for nedlasting.

Eksempel

{
  "type": "dissemination.delivered",
  "timestamp": "2025-10-02T09:18:01.160+02:00",
  "data": {
    "archiveId": "019e404e-60ab-7457-b7c9-94c453242c69",
    "disseminationId": "5MfwdzCjkYW4c79MYorXy9",
    "objectId": "digifoto_ae0690eb-22bf-4996-a6a0-9273b7cd9256",
    "clientId": "kulturit",
    "contractId": "2d17",
    "sumSizeInBytes": "1",
    "files": [
      {
        "downloadURL": "https://minio.dev.nb.no/submission-service-stage/dissemination/5MfwdzCjkYW4c79MYorXy9/68d3a838a0be2b1d75eeef75/primary_20250325.tar?...",
        "filename": "primary_20250325.tar",
        "filesize": 3481600,
        "expirationDate": "2025-10-03T09:18:01.023897767+02:00",
        "checksum": "ae958c69059974c63980035882d2178c",
        "checksumAlgorithm": "MD5"
      }
    ]
  }
}

Støtte

Trenger du hjelp eller har spørsmål, kontakt teamet for digital bevaring ved Nasjonalbiblioteket.

API-referanse

For fullstendig informasjon om endepunkter, parametere, skjema og statuser, se Swagger-dokumentasjonen.