Submission Service

Overview

The Submission Service API allows clients to submit digital objects for long-term preservation. For general information on authentication and authorization, please refer to the main API documentation.

This documentation complements the detailed API reference available through Swagger UI at https://digitalpreservation.no/swagger/.

For general information on authentication and authorization, please refer to the main API documentation.

File Size Limitations:

Maximum file size: 5 GB per file
This limitation is due to constraints with S3 pre-signed URLs used for direct file uploads

Workflow

The complete submission process follows these steps:

Create a submission with metadata
Register files to get pre-signed upload URLs
Upload files to the provided URLs
Finalize the submission to initiate preservation processing
Track the submission status as it progresses through the preservation system (at a later stage we will support status updates)

Example API Usage

Register a new submission

POST /v1/contracts/{contractId}/submissions

Request

POST /dps-submission/v1/contracts/1234/submissions HTTP/1.1
Host: api.nb.no
Content-Type: application/json
Authorization: Bearer eyJhbGciOxxxxxxx

{
  "objectId": "digavis_aabcc",
  "priority": 50,
  "metadata": {
    "type": "Artikkel",
    "identifier": [
      {
        "type": "URN",
        "value": "URN:NBN:no-nb_plfut_00001"
      }
    ],
    "title": {
      "value": "My Book Title",
      "lang": "eng"
    },
    "alternative": [
      {
        "type": "Original title",
        "value": "My Alternative Book Title",
        "lang": "eng"
      }
    ],
    "creator": [
      {
        "name": "Marek, Václav",
        "type": "Person",
        "role": "Fotograf",
        "authority": {
          "source": "Example authority",
          "code": "198097",
          "uri": "https://example.com/198097"
        }
      }
    ],
    "contributor": [
      {
        "name": "Nordmann, Ola",
        "type": "Person",
        "role": "Avbildet",
        "authority": {
          "source": "Example authority",
          "code": "198097",
          "uri": "https://example.com/198097"
        }
      }
    ],
    "publisher": [
      {
        "name": "Gyldendal",
        "type": "Organization",
        "authority": {
          "source": "Example authority",
          "code": "198097",
          "uri": "https://example.com/198097"
        }
      }
    ],
    "spatial": [
      {
        "name": "Mo i Rana",
        "type": "Place",
        "authority": {
          "source": "Example authority",
          "code": "198097",
          "uri": "https://example.com/198097"
        },
        "coordinateReferenceSystem": "EPSG:4326",
        "latitude": 67.2968,
        "longitude": 14.3974
      }
    ],
    "date": [
      {
        "type": "created",
        "value": "2023-10-27"
      }
    ],
    "language": [
      {
        "type": "Subtitles",
        "value": "Swedish",
        "lang": "eng"
      }
    ],
    "isPartOf": [
      {
        "value": "Chronicles of Narnia",
        "lang": "eng"
      }
    ],
    "provenance": [
      {
        "value": "The collection was donated to the National Library by Václav Marek 1979-05-12",
        "lang": "eng"
      }
    ],
    "subject": [
      {
        "lang": "nob",
        "value": "Norge"
      }
    ],
    "description": [
      {
        "lang": "nob",
        "value": "Norge"
      }
    ]
  }
}

Response (201 Created)

{
  "contractId": "1234",
  "submissionId": "8Z7x1T9rN0Xc2B5Yq4L3zP",
  "objectId": "digavis_aabcc",
  "clientId": "myClientId",
  "status": "REGISTERED",
  "priority": 50
}

Register a file for upload

Request

POST /dps-submission/v1/contracts/1234/submissions/8Z7x1T9rN0Xc2B5Yq4L3zP/files HTTP/1.1
Host: api.nb.no
Content-Type: application/json
Authorization: Bearer eyJhbGciOxxxxxxx

{
  "filePath": "representations/primary_20250217/data/ranablad_20250215.pdf",
  "checksum": "d41d8cd98f00b204e9800998ecf8427e",
  "isPackaged": false
}

Response

{
  "fileId": "1M0x4T9rN8Xc7B2Yq5L3zK",
  "filePath": "representations/primary_20250217/data/ranablad_20250215.pdf",
  "checksum": "d41d8cd98f00b204e9800998ecf8427e",
  "isPackaged": false,  
  "uploadUrl": "https://s3.nb.no/examplebucket/...&X-Amz-Signature=..."
}

Finalize the submission after upload

Request

POST /dps-submission/v1/contracts/1234/submissions/8Z7x1T9rN0Xc2B5Yq4L3zP/finalize HTTP/1.1
Host: api.nb.no
Authorization: Bearer eyJhbGciOxxxxxxx

Response

{
  "contractId": "1234",
  "submissionId": "8Z7x1T9rN0Xc2B5Yq4L3zP",
  "objectId": "digavis_aabcc",
  "clientId": "myClientId",
  "status": "UPLOAD_COMPLETED",
  "priority": 50,
  "sumSizeInBytes": 12345678,
  "files": [
    {
      "fileId": "1M0x4T9rN8Xc7B2Yq5L3zK",
      "filePath": "representations/primary_20250217/data/ranablad_20250215.pdf",
      "s3ObjectKey": "myClientId/1234/8Z7x1T9rN0Xc2B5Yq4L3zP/representations/primary_20250217/data/ranablad_20250215.pdf",
      "checksum": "d41d8cd98f00b204e9800998ecf8427e",
      "isPackaged": false,
      "uploadUrl": "https://s3.nb.no/examplebucket/...&X-Amz-Signature=..."
    }
  ]
}

File Upload Process

The file upload process in the Digital Preservation Submission Service consists of the following steps:

Register a file by making a POST request to /contracts/{contractId}/submissions/{submissionId}/files with file metadata
Receive a pre-signed upload URL in the response, which is valid for a limited time (typically 1 hour)
Upload the file content directly to our S3 compatible storage using the pre-signed URL with an HTTP PUT request

Pre-signed URL Usage

The pre-signed URL allows for secure direct uploads to S3 without requiring credentials:

PUT {pre-signed-url} HTTP/1.1
Content-Length: {file-size}

[FILE CONTENT]

Upload Requirements

The file must be uploaded using the pre-signed URL provided during registration
The file content must generate the same MD5 checksum provided during registration

Handling Upload Failures

If an upload fails or times out:

You can retry the upload using the same pre-signed URL if it hasn’t expired
If the URL has expired, delete the file registration and register it again to get a new URL

Status Lifecycle

A submission progresses through the following statuses:

REGISTERED - Initial state when a submission is created
UPLOAD_COMPLETED - All files have been uploaded and the submission has been finalized
TRANSFERRING - The submission is being transferred from S3 Storage to the preservation system
VALIDATING - The submission is being validated for integrity and completeness
ARCHIVING - The submission is being archived in the preservation system
PRESERVED - The submission has been successfully preserved
REJECTED - The submission has been rejected due to validation errors or other issues

Best Practices

Always verify checksums before uploading files to ensure data integrity
Use unique objectIds within each contract to avoid conflicts
Include comprehensive metadata to enhance discoverability and preservation
Implement proper error handling in your client application

Support

For API support, please contact the Digital Preservation team.

API Reference

For complete API details including endpoints, parameters, request/response schemas, and status codes, please refer to the Swagger documentation.

Last updated on 2025-10-07 - Github commit history ↗