LOCKSS Repository Service REST API

REST API of the LOCKSS Repository Service

More information: https://www.lockss.org/

Contact Info: lockss-support@lockss.org

Version: 2.0.0

BasePath:/

BSD-3-Clause

https://opensource.org/licenses/BSD-3-Clause

Access

Methods

[ Jump to Models ]

Artifacts

post /archives

Imports artifacts from an archive (addArtifacts)

Consumes

This API call consumes the following media types via the request header:

multipart/form-data

Query parameters

namespace (optional)

Query Parameter — Namespace of the artifacts default: lockss

storeDuplicate (optional)

Query Parameter — If true, artifacts with duplicate content will be stored, otherwise suppressed default: false

excludeStatusPattern (optional)

Query Parameter — If supplied, WARC records whose HTTP response status code matches the regular expression will not be imported

Form parameters

auid (required)

Form Parameter —

archive (required)

Form Parameter — format: binary

Return type

byte[]

Example data

Content-Type: application/json

""

Produces

This API call produces the following media types according to the request header; the media type will be conveyed by the response header.

application/json

Responses

200

Status of artifacts imported from the archive, maybe partially. Return body is a sequence of JSON ImportStatus objects. byte[]

400

Invalid input

401

Unauthorized request

403

Client not authorized to create artifacts

502

Internal error creating artifact

post /artifacts

Create an artifact (createArtifact)

Consumes

This API call consumes the following media types via the request header:

multipart/form-data

Form parameters

artifactProps (required)

Form Parameter —

httpResponseHeader (required)

Form Parameter —

payload (required)

Form Parameter — format: binary

Return type

artifact

Example data

Content-Type: application/json

{
  "committed" : true,
  "storageUrl" : "storageUrl"
}

Produces

This API call produces the following media types according to the request header; the media type will be conveyed by the response header.

application/json

Responses

201

Artifact created artifact

302

Duplicate content; artifact not created

400

Invalid input

401

Unauthorized request

403

Client not authorized to create artifacts

502

Internal error creating artifact

delete /artifacts/{uuid}

Remove an artifact from the repository (deleteArtifact)

Path parameters

uuid (required)

Path Parameter — Identifier of the artifact

Query parameters

namespace (optional)

Query Parameter — Namespace of the artifacts default: lockss

Responses

200

Successfully removed artifact

401

Unauthorized request

403

Client not authorized to delete artifact

404

Artifact not found

409

Cannot delete artifact

get /artifacts/{uuid}

Get artifact and metadata (getArtifactDataByMultipart)

Path parameters

uuid (required)

Path Parameter — Identifier of the artifact

Query parameters

namespace (optional)

Query Parameter — Namespace of the artifacts default: lockss

includeContent (optional)

Query Parameter — Controls whether to include the artifact content part in multipart response default: ALWAYS

Return type

byte[]

Example data

Content-Type: application/json

""

Produces

This API call produces the following media types according to the request header; the media type will be conveyed by the response header.

multipart/form-data
application/json

Responses

200

Multipart/form-data containing the following parts: The artifact properties, HTTP status and headers if present, and the artifact's payload if requested. See POST /artifacts for more information. byte[]

401

Unauthorized request

403

Client not authorized to retrieve artifact

404

Artifact not found

500

Internal Server Error

502

Could not read from external resource

get /artifacts/{uuid}/payload

Get artifact payload (getArtifactDataByPayload)

Path parameters

uuid (required)

Path Parameter — Identifier of the artifact

Query parameters

namespace (optional)

Query Parameter — Namespace of the artifacts default: lockss

includeContent (optional)

Query Parameter — Controls whether to include the artifact content part in multipart response default: ALWAYS

Return type

byte[]

Example data

Content-Type: application/json

""

Produces

This API call produces the following media types according to the request header; the media type will be conveyed by the response header.

application/octet-stream

Responses

200

Artifact's payload byte[]

401

Unauthorized request

403

Client not authorized to retrieve artifact

404

Artifact not found

500

Internal Server Error

502

Could not read artifact

get /artifacts/{uuid}/response

Get artifact data as HTTP response (getArtifactDataByResponse)

Path parameters

uuid (required)

Path Parameter — Identifier of the artifact

Query parameters

namespace (optional)

Query Parameter — Namespace of the artifacts default: lockss

includeContent (optional)

Query Parameter — Controls whether to include the artifact content part in multipart response default: ALWAYS

Return type

byte[]

Example data

Content-Type: application/json

""

Produces

This API call produces the following media types according to the request header; the media type will be conveyed by the response header.

application/http;msgtype=response

Responses

200

Artifact's payload byte[]

401

Unauthorized request

403

Client not authorized to retrieve artifact

404

Artifact not found

500

Internal Server Error

502

Could not read artifact

get /aus/{auid}/artifacts

Get artifacts in an Archival Unit (getArtifacts)

Get a list of all artifacts in a namespace and Archival Unit or a pageful of the list defined by the continuation token and size

Path parameters

auid (required)

Path Parameter — Identifier of the Archival Unit containing the artifacts

Query parameters

namespace (optional)

Query Parameter — Namespace of the artifacts default: lockss

url (optional)

Query Parameter — The URL contained by the artifacts

urlPrefix (optional)

Query Parameter — The prefix to be matched by the artifact URLs

version (optional)

Query Parameter — The version of the artifact

includeUncommitted (optional)

Query Parameter — Indication of whether uncommitted artifacts should be returned

limit (optional)

Query Parameter — The requested maximum number of artifacts per response

continuationToken (optional)

Query Parameter — The continuation token of the next page of artifacts to be returned

Return type

artifactPageInfo

Example data

Content-Type: application/json

{
  "pageInfo" : {
    "curLink" : "curLink",
    "resultsPerPage" : 6,
    "totalCount" : 0,
    "continuationToken" : "continuationToken",
    "nextLink" : "nextLink"
  },
  "artifacts" : [ {
    "committed" : true,
    "storageUrl" : "storageUrl"
  }, {
    "committed" : true,
    "storageUrl" : "storageUrl"
  } ]
}

Produces

This API call produces the following media types according to the request header; the media type will be conveyed by the response header.

application/json

Responses

200

The requested artifacts artifactPageInfo

401

Unauthorized request

403

Client not authorized to retrieve data

404

AUID not found in namespace

502

Could not read from external resource

get /artifacts

Returns all artifacts that match a given a URL or URL prefix and/or version. (getArtifactsFromAllAus)

Query parameters

namespace (optional)

Query Parameter — Namespace of the artifacts default: lockss

url (optional)

Query Parameter — The URL contained by the artifacts

urlPrefix (optional)

Query Parameter — The prefix to be matched by the artifact URLs

versions (optional)

Query Parameter — Versions of the artifacts to return default: all

limit (optional)

Query Parameter — The requested maximum number of artifacts per response

continuationToken (optional)

Query Parameter — The continuation token of the next page of artifacts to be returned

Return type

artifactPageInfo

Example data

Content-Type: application/json

{
  "pageInfo" : {
    "curLink" : "curLink",
    "resultsPerPage" : 6,
    "totalCount" : 0,
    "continuationToken" : "continuationToken",
    "nextLink" : "nextLink"
  },
  "artifacts" : [ {
    "committed" : true,
    "storageUrl" : "storageUrl"
  }, {
    "committed" : true,
    "storageUrl" : "storageUrl"
  } ]
}

Produces

This API call produces the following media types according to the request header; the media type will be conveyed by the response header.

application/json

Responses

200

The requested artifacts artifactPageInfo

401

Unauthorized request

403

Client not authorized to retrieve data

404

Collection not found

502

Could not read from external resource

put /artifacts/{uuid}

Update the property of an artifact (updateArtifact)

Path parameters

uuid (required)

Path Parameter — Identifier of the artifact

Consumes

This API call consumes the following media types via the request header:

multipart/form-data

Query parameters

namespace (optional)

Query Parameter — Namespace of the artifacts default: lockss

Form parameters

committed (required)

Form Parameter —

Return type

artifact

Example data

Content-Type: application/json

{
  "committed" : true,
  "storageUrl" : "storageUrl"
}

Produces

This API call produces the following media types according to the request header; the media type will be conveyed by the response header.

application/json

Responses

200

Artifact updated artifact

400

Invalid input

401

Unauthorized request

403

Client not authorized to update artifact

404

Artifact not found

Aus

get /aus/{auid}/size

Get the size of Archival Unit artifacts in a namespace (getArtifactsSize)

Path parameters

auid (required)

Path Parameter — Identifier of the Archival Unit containing the artifacts

Query parameters

namespace (optional)

Query Parameter — Namespace of the artifacts default: lockss

Return type

auSize

Example data

Content-Type: application/json

{
  "totalLatestVersions" : 0,
  "totalWarcSize" : 1,
  "totalAllVersions" : 6
}

Produces

This API call produces the following media types according to the request header; the media type will be conveyed by the response header.

application/json

Responses

200

Returns an AuSize containing the sizes of all the artifacts, only the latest artifact version of all URLs, and the sum of the size of all the underlying WARC files, of an AU. auSize

401

Unauthorized request

403

Client not authorized to retrieve data

404

AUID not found in namespace

502

Could not read from external resource

get /aus

Get Archival Unit IDs (AUIDs) in a namespace (getAus)

Get a list of all Archival Unit identifiers in a namespace or a pageful of the list defined by the continuation token and size

Query parameters

namespace (optional)

Query Parameter — Namespace of the artifacts default: lockss

limit (optional)

Query Parameter — The requested maximum number of Archival Unit identifiers per response

continuationToken (optional)

Query Parameter — The continuation token of the next page of Archival Unit identifiers to be returned

Return type

auidPageInfo

Example data

Content-Type: application/json

{
  "pageInfo" : {
    "curLink" : "curLink",
    "resultsPerPage" : 6,
    "totalCount" : 0,
    "continuationToken" : "continuationToken",
    "nextLink" : "nextLink"
  },
  "auids" : [ "auids", "auids" ]
}

Produces

This API call produces the following media types according to the request header; the media type will be conveyed by the response header.

application/json

Responses

200

The requested Archival Unit identifiers auidPageInfo

401

Unauthorized request

403

Client not authorized to retrieve data

404

No AUIDs in namespace

502

Could not read from external resource

post /aus/{auid}/bulk

Marks the AUID for bulk artifact transfer (handleBulkAuOp)

Path parameters

auid (required)

Path Parameter — Archival Unit ID

Consumes

This API call consumes the following media types via the request header:

multipart/form-data

Query parameters

namespace (optional)

Query Parameter — Namespace of the artifacts default: lockss

Form parameters

op (required)

Form Parameter —

Responses

200

Bulk operation succeeded

401

Unauthorized

403

Client is forbidden from performing bulk operation

404

AUID not in bulk mode

Repo

get /namespaces

Get namespaces of the committed artifacts in the repository (getNamespaces)

Return type

array[String]

Example data

Content-Type: application/json

[ "", "" ]

Produces

This API call produces the following media types according to the request header; the media type will be conveyed by the response header.

application/json

Responses

200

Status 200

get /repoinfo

Get repository information (getRepositoryInformation)

Get properties of the repository

Return type

repositoryInfo

Example data

Content-Type: application/json

{
  "storeInfo" : {
    "avail" : 1,
    "percentUsedString" : "percentUsedString",
    "size" : 0,
    "name" : "name",
    "percentUsed" : 5.962133916683182,
    "used" : 6,
    "type" : "type"
  }
}

Produces

This API call produces the following media types according to the request header; the media type will be conveyed by the response header.

application/json

Responses

200

The repository information repositoryInfo

401

Unauthorized

500

Internal Server Error

get /repoinfo/storage

Get repository storage information (getStorageInfo)

Get properties of the repository storage

Return type

storageInfo

Example data

Content-Type: application/json

{
  "avail" : 1,
  "percentUsedString" : "percentUsedString",
  "size" : 0,
  "name" : "name",
  "percentUsed" : 5.962133916683182,
  "used" : 6,
  "type" : "type"
}

Produces

This API call produces the following media types according to the request header; the media type will be conveyed by the response header.

application/json

Responses

200

The repository storage information storageInfo

401

Unauthorized

500

Internal Server Error

get /checksumalgorithms

Get the supported checksum algorithms (getSupportedChecksumAlgorithms)

Get a list of the names of the supported checksum algorithms

Return type

array[String]

Example data

Content-Type: application/json

[ "", "" ]

Produces

This API call produces the following media types according to the request header; the media type will be conveyed by the response header.

application/json

Responses

200

The names of the supported checksum algorithms

400

Bad Request

401

Unauthorized

500

Internal Server Error

Status

get /status

Get the status of the service (getStatus)

Get the status of the service

Return type

apiStatus

Example data

Content-Type: application/json

{
  "startupStatus" : "NONE",
  "reason" : "reason",
  "readyTime" : 0,
  "apiVersion" : "apiVersion",
  "ready" : true,
  "componentName" : "componentName",
  "componentVersion" : "componentVersion",
  "serviceName" : "serviceName",
  "lockssVersion" : "lockssVersion"
}

Produces

This API call produces the following media types according to the request header; the media type will be conveyed by the response header.

application/json

Responses

200

The status of the service apiStatus

401

Unauthorized

500

Internal Server Error

Wayback

get /wayback/cdx/owb/{namespace}

Get OpenWayback CDX records (getCdxOwb)

Get the OpenWayback CDX records of a URL in a namespace

Path parameters

namespace (required)

Path Parameter — Namespace of the artifacts

Request headers

Query parameters

q (optional)

Query Parameter — Query string. Supported fields are url, type\ \ (urlquery/prefixquery), offset and limit.

count (optional)

Query Parameter — .

start_page (optional)

Query Parameter — .

Return type

String

Example data

Content-Type: application/json

""

Produces

This API call produces the following media types according to the request header; the media type will be conveyed by the response header.

application/xml

Responses

200

The OpenWayback CDX records of the URL in the namespace String

401

Unauthorized

403

Forbidden

404

Namespace/URL not found

500

Internal Server Error

get /wayback/cdx/pywb/{namespace}

Get PyWayback CDX records (getCdxPywb)

Get the PyWayback CDX records of a URL in a namespace

Path parameters

namespace (required)

Path Parameter — Namespace of the artifacts

Request headers

Query parameters

url (optional)

Query Parameter — The URL for which the CDX records are requested

limit (optional)

Query Parameter — .

matchType (optional)

Query Parameter —

sort (optional)

Query Parameter —

closest (optional)

Query Parameter — Timestamp for sort=closest mode

output (optional)

Query Parameter — Output format

fl (optional)

Query Parameter — Comma-separated list of fields to include in output

Return type

String

Example data

Content-Type: application/json

""

Produces

This API call produces the following media types according to the request header; the media type will be conveyed by the response header.

text/plain

Responses

200

The PyWayback CDX records of the URL in the namespace String

401

Unauthorized

403

Forbidden

404

Namespace/URL not found

500

Internal Server Error

get /wayback/warcs/{fileName}

Get a WARC archive (getWarcArchive)

Get the contents of a single WARC record as a WARC archive

Path parameters

fileName (required)

Path Parameter — Name of the WARC archive

Request headers

Return type

byte[]

Example data

Content-Type: application/json

""

Produces

This API call produces the following media types according to the request header; the media type will be conveyed by the response header.

application/warc

Responses

200

The contents of the requested WARC archive byte[]

401

Unauthorized

404

WARC archive not found

500

Internal Server Error

Models

[ Jump to Methods ]

apiStatus
archives_body
artifact
artifactPageInfo
artifactProperties
artifacts_body
artifacts_uuid_body
auSize
auidPageInfo
auid_bulk_body
importStatus
pageInfo
repositoryInfo
storageInfo
streamingResponseBody

`apiStatus` Up

The status information of the service

apiVersion

String The version of the API

componentName (optional)

String The name of the component

componentVersion (optional)

String The version of the component software

lockssVersion (optional)

String The version of the LOCKSS system

ready

Boolean The indication of whether the service is available

serviceName (optional)

String The name of the service

readyTime (optional)

Long The time the service last became ready. format: int64

reason (optional)

String The reason the service isn't ready.

startupStatus (optional)

String Enum indicating progress of plugin/AU processing at startup.

Enum:

NONE

PLUGINS_CRAWLING

PLUGINS_COLLECTED

PLUGINS_LOADING

PLUGINS_LOADED

AUS_STARTING

AUS_STARTED

`archives_body` Up

auid

String Archival Unit ID (AUID) of new artifact

`artifact` Up

namespace (optional)

String

uuid (optional)

String

auid (optional)

String

uri (optional)

String

version (optional)

Integer

contentLength (optional)

Long format: int64

contentDigest (optional)

String

collectionDate (optional)

Long format: int64

storeDate (optional)

Long format: int64

state (optional)

String

committed (optional)

Boolean

storageUrl (optional)

String

`artifactPageInfo` Up

A display page of artifacts

artifacts

array[artifact] The artifacts included in the page

pageInfo

`artifactProperties` Up

namespace (optional)

String

uuid (optional)

String

auid (optional)

String

uri (optional)

String

version (optional)

Integer

contentLength (optional)

Long format: int64

contentDigest (optional)

String

collectionDate (optional)

Long format: int64

storeDate (optional)

Long format: int64

state (optional)

String

`artifacts_body` Up

artifactProps

String Artifact properties (JSON)

httpResponseHeader (optional)

String HTTP response status and headers (optional)

payload

byte[] Artifact payload data format: binary

`artifacts_uuid_body` Up

committed

Boolean New commit status of artifact

`auSize` Up

totalLatestVersions (optional)

Long format: int64

totalAllVersions (optional)

Long format: int64

totalWarcSize (optional)

Long format: int64

`auidPageInfo` Up

A display page of Archival Unit identifiers

auids

array[String] The Archival Unit identifiers included in the page

pageInfo

`auid_bulk_body` Up

String Bulk AU transfer operation

Enum:

start

finish

`importStatus` Up

warcId (optional)

String

offset (optional)

Long format: int64

url (optional)

String

artifactUuid (optional)

String

digest (optional)

String

version (optional)

Integer

status (optional)

String

Enum:

ERROR

DUPLICATE

EXCLUDED

statusMessage (optional)

String

`pageInfo` Up

The information related to pagination of content

totalCount

Integer The total number of results format: int32

resultsPerPage

Integer The number of results per page format: int32

continuationToken

String The continuation token

curLink

String The link of the current request

nextLink

String The link of the next request

`repositoryInfo` Up

Information about the repository

storeInfo

storageInfo

indexInfo

storageInfo

`storageInfo` Up

Information about a repository storage area

type

String Type of the storage area

name

String Name of the storage area

size

Long Size in bytes of the storage area format: int64

used

Long Used size in bytes of the torage area format: int64

avail

Long Available size in bytes of the storage area format: int64

percentUsedString

String Percentage of size used, formatted as a string

percentUsed

Double Percentage of size used format: double

LOCKSS Repository Service REST API

Access

Table of Contents

Consumes

Query parameters

Form parameters

Return type

Example data

Produces

Responses

200

400

401

403

502

Consumes

Form parameters

Return type

Example data

Produces

Responses

201

302

400

401

403

502

Path parameters

Query parameters

Responses

200

401

403

404

409

Path parameters

Query parameters

Return type

Example data

Produces

Responses

200

401

403

404

500

502

Path parameters

Query parameters

Return type

Example data

Produces

Responses

200

401

403

404

500

502

Path parameters

Query parameters

Return type

Example data

Produces

Responses

200

401

403

404

500

502

Path parameters

Query parameters

Return type

Example data

Produces

Responses

200

401

403