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 ]

Table of Contents

Artifacts

Aus

Repo

Status

Wayback

Artifacts

Up
post /archives
Imports artifacts from an archive (addArtifacts)

Consumes

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

Query parameters

namespace (optional)
Query Parameter — Namespace of the artifacts default: lockss

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 Accept request header; the media type will be conveyed by the Content-Type response header.

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

Up
post /artifacts
Create an artifact (createArtifact)

Consumes

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

Form parameters

artifactProps (required)
Form Parameter
httpStatus (required)
Form Parameter
httpHeaders (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 Accept request header; the media type will be conveyed by the Content-Type response header.

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

Up
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

Up
get /artifacts/{uuid}
Get artifact and metadata (getArtifact)

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 Accept request header; the media type will be conveyed by the Content-Type response header.

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

502

Could not read from external resource

Up
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 Accept request header; the media type will be conveyed by the Content-Type response header.

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

Up
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 Accept request header; the media type will be conveyed by the Content-Type response header.

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

Up
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 Content-Type request header:

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 Accept request header; the media type will be conveyed by the Content-Type response header.

Responses

200

Artifact updated artifact

400

Invalid input

401

Unauthorized request

403

Client not authorized to update artifact

404

Artifact not found

Aus

Up
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 Accept request header; the media type will be conveyed by the Content-Type response header.

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

Up
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 Accept request header; the media type will be conveyed by the Content-Type response header.

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

Up
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 Content-Type request header:

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

Up
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 Accept request header; the media type will be conveyed by the Content-Type response header.

Responses

200

Status 200

Up
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 Accept request header; the media type will be conveyed by the Content-Type response header.

Responses

200

The repository information repositoryInfo

401

Unauthorized

500

Internal Server Error

Up
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 Accept request header; the media type will be conveyed by the Content-Type response header.

Responses

200

The names of the supported checksum algorithms

400

Bad Request

401

Unauthorized

500

Internal Server Error

Status

Up
get /status
Get the status of the service (getStatus)
Get the status of the service

Return type

apiStatus

Example data

Content-Type: application/json
{
  "apiVersion" : "apiVersion",
  "ready" : true,
  "componentName" : "componentName",
  "componentVersion" : "componentVersion",
  "serviceName" : "serviceName",
  "lockssVersion" : "lockssVersion"
}

Produces

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

Responses

200

The status of the service apiStatus

401

Unauthorized

500

Internal Server Error

Wayback

Up
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 Accept request header; the media type will be conveyed by the Content-Type response header.

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

Up
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 Accept request header; the media type will be conveyed by the Content-Type response header.

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

Up
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 Accept request header; the media type will be conveyed by the Content-Type response header.

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 ]

Table of Contents

  1. apiStatus
  2. archives_body
  3. artifact
  4. artifactPageInfo
  5. artifactProperties
  6. artifacts_body
  7. artifacts_uuid_body
  8. auSize
  9. auidPageInfo
  10. auid_bulk_body
  11. importStatus
  12. pageInfo
  13. repositoryInfo
  14. storageInfo
  15. streamingResponseBody

apiStatus Up

The status information of the service
apiVersion
String The version of the API
componentName
String The name of the component
componentVersion
String The version of the component software
lockssVersion
String The version of the LOCKSS system
ready
Boolean The indication of whether the service is available
serviceName
String The name of the service

archives_body Up

auid
String Archival Unit ID (AUID) of new artifact
archive
byte[] Archive data containing artifacts format: binary

artifact Up

namespace (optional)
uuid (optional)
auid (optional)
uri (optional)
version (optional)
contentLength (optional)
Long format: int64
contentDigest (optional)
collectionDate (optional)
Long format: int64
state (optional)
committed (optional)
storageUrl (optional)

artifactPageInfo Up

A display page of artifacts
artifacts
array[artifact] The artifacts included in the page
pageInfo

artifactProperties Up

namespace (optional)
uuid (optional)
auid (optional)
uri (optional)
version (optional)
contentLength (optional)
Long format: int64
contentDigest (optional)
collectionDate (optional)
Long format: int64
state (optional)

artifacts_body Up

artifactProps
String Artifact properties (JSON)
httpStatus (optional)
String HTTP status (optional)
httpHeaders (optional)
String HTTP 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

op
String Bulk AU transfer operation
Enum:
start
finish

importStatus Up

warcId (optional)
offset (optional)
Long format: int64
url (optional)
artifactUuid (optional)
digest (optional)
version (optional)
status (optional)
Enum:
OK
ERROR
statusMessage (optional)

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
indexInfo

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

streamingResponseBody Up