swagger.swagger.yaml Maven / Gradle / Ivy
The newest version!
# Copyright (c) 2000-2020, Board of Trustees of Leland Stanford Jr. University
# All rights reserved.
#
# Redistribution and use in source and binary forms, with or without
# modification, are permitted provided that the following conditions are met:
#
# 1. Redistributions of source code must retain the above copyright notice,
# this list of conditions and the following disclaimer.
#
# 2. Redistributions in binary form must reproduce the above copyright notice,
# this list of conditions and the following disclaimer in the documentation
# and/or other materials provided with the distribution.
#
# 3. Neither the name of the copyright holder nor the names of its contributors
# may be used to endorse or promote products derived from this software without
# specific prior written permission.
#
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 'AS IS'
# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
# POSSIBILITY OF SUCH DAMAGE.
openapi: 3.0.1
info:
title: LOCKSS Repository Service REST API
description: REST API of the LOCKSS Repository Service
contact:
name: LOCKSS Support
url: 'https://www.lockss.org/'
email: [email protected]
license:
name: BSD-3-Clause
url: 'https://opensource.org/licenses/BSD-3-Clause'
version: 2.0.0
servers:
- url: http://laaws.lockss.org:443/
tags:
- name: Default
description: Default section
- name: repository
description: Tasks on the repository
paths:
/namespaces:
get:
tags:
- repo
summary: Get namespaces of the committed artifacts in the repository
operationId: getNamespaces
responses:
'200':
description: Status 200
content:
application/json:
schema:
type: array
items:
type: string
default:
description: The resulting error payload.
content:
application/json:
schema:
type: object
/archives:
post:
tags:
- artifacts
summary: Imports artifacts from an archive
operationId: addArtifacts
parameters:
- name: namespace
in: query
description: Namespace of the artifacts
schema:
type: string
default: lockss
- name: storeDuplicate
in: query
description: 'If true, artifacts with duplicate content will be stored, otherwise suppressed'
schema:
type: boolean
default: false
- name: excludeStatusPattern
in: query
description: 'If supplied, WARC records whose HTTP response status code matches the regular expression will not be imported'
schema:
type: string
requestBody:
required: true
content:
multipart/form-data:
schema:
required:
- archive
- auid
type: object
properties:
auid:
description: Archival Unit ID (AUID) of new artifact
type: string
archive:
description: Archive data containing artifacts
type: string
format: binary
responses:
'200':
description: 'Status of artifacts imported from the archive, maybe partially. Return body is a sequence of JSON ImportStatus objects.'
content:
application/json:
schema:
type: string
format: binary
default:
description: The resulting error payload.
content:
application/json:
schema:
type: object
/artifacts:
get:
tags:
- artifacts
summary: Returns all artifacts that match a given a URL or URL prefix and/or version.
operationId: getArtifactsFromAllAus
parameters:
- name: namespace
in: query
description: Namespace of the artifacts
schema:
type: string
default: lockss
- name: url
in: query
description: The URL contained by the artifacts
schema:
type: string
- name: urlPrefix
in: query
description: The prefix to be matched by the artifact URLs
schema:
type: string
- name: versions
in: query
description: Versions of the artifacts to return
schema:
type: string
default: all
enum:
- all
- latest
- name: limit
in: query
description: The requested maximum number of artifacts per response
schema:
type: integer
- name: continuationToken
in: query
description: The continuation token of the next page of artifacts to be returned
schema:
type: string
responses:
'200':
description: The requested artifacts
content:
application/json:
schema:
$ref: '#/components/schemas/artifactPageInfo'
default:
description: The resulting error payload.
content:
application/json:
schema:
type: object
post:
tags:
- artifacts
summary: Create an artifact
operationId: createArtifact
requestBody:
content:
multipart/form-data:
schema:
required:
- artifactProps
- payload
type: object
properties:
artifactProps:
description: Artifact properties (JSON)
type: string
payload:
description: Artifact payload data
type: string
format: binary
httpResponseHeader:
type: string
description: HTTP response status and headers (optional)
responses:
'201':
description: Artifact created
content:
application/json:
schema:
$ref: '#/components/schemas/artifact'
'302':
description: Duplicate content; artifact not created
headers:
Location:
description: Repository query URL to duplicate artifacts
schema:
type: string
content: { }
default:
description: The resulting error payload.
content:
application/json:
schema:
type: object
'/artifacts/{uuid}':
get:
tags:
- artifacts
summary: Get artifact and metadata
operationId: getArtifactDataByMultipart
parameters:
- name: namespace
in: query
description: Namespace of the artifacts
schema:
type: string
default: lockss
- name: uuid
in: path
description: Identifier of the artifact
required: true
schema:
type: string
- name: includeContent
in: query
description: Controls whether to include the artifact content part in multipart response
schema:
type: string
default: ALWAYS
enum:
- NEVER
- IF_SMALL
- ALWAYS
responses:
'200':
description: "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."
content:
multipart/form-data:
schema:
type: string
format: binary
application/json:
schema:
type: string
format: binary
default:
description: The resulting error payload.
content:
application/json:
schema:
type: object
put:
tags:
- artifacts
summary: Update the property of an artifact
operationId: updateArtifact
parameters:
- name: namespace
in: query
description: Namespace of the artifacts
schema:
type: string
default: lockss
- name: committed
in: query
description: Committed status of the artifact
required: true
schema:
type: boolean
- name: uuid
in: path
description: Identifier of the artifact
required: true
schema:
type: string
responses:
'200':
description: Artifact updated
content:
application/json:
schema:
$ref: '#/components/schemas/artifact'
default:
description: The resulting error payload.
content:
application/json:
schema:
type: object
delete:
tags:
- artifacts
summary: Remove an artifact from the repository
operationId: deleteArtifact
parameters:
- name: namespace
in: query
description: Namespace of the artifacts
schema:
type: string
default: lockss
- name: uuid
in: path
description: Identifier of the artifact
required: true
schema:
type: string
responses:
'200':
description: Successfully removed artifact
content: { }
default:
description: The resulting error payload.
content:
application/json:
schema:
type: object
/artifacts/{uuid}/payload:
get:
tags:
- artifacts
summary: Get artifact payload
operationId: getArtifactDataByPayload
parameters:
- name: namespace
in: query
description: Namespace of the artifacts
schema:
type: string
default: lockss
- name: uuid
in: path
description: Identifier of the artifact
required: true
schema:
type: string
- name: includeContent
in: query
description: Controls whether to include the artifact content part in multipart response
schema:
type: string
default: ALWAYS
enum:
- NEVER
- IF_SMALL
- ALWAYS
responses:
'200':
description: Artifact's payload
content:
application/octet-stream:
schema:
type: string
format: binary
default:
description: The resulting error payload.
content:
application/json:
schema:
type: object
/artifacts/{uuid}/response:
get:
tags:
- artifacts
summary: Get artifact data as HTTP response
operationId: getArtifactDataByResponse
parameters:
- name: namespace
in: query
description: Namespace of the artifacts
schema:
type: string
default: lockss
- name: uuid
in: path
description: Identifier of the artifact
required: true
schema:
type: string
- name: includeContent
in: query
description: Controls whether to include the artifact content part in multipart
response
schema:
type: string
default: ALWAYS
enum:
- NEVER
- IF_SMALL
- ALWAYS
responses:
'200':
description: Artifact's payload
content:
application/http;msgtype=response:
schema:
type: string
format: binary
default:
description: The resulting error payload.
content:
application/json:
schema:
type: object
/aus:
get:
tags:
- aus
summary: Get Archival Unit IDs (AUIDs) in a namespace
description: Get a list of all Archival Unit identifiers in a namespace or a
pageful of the list defined by the continuation token and size
operationId: getAus
parameters:
- name: namespace
in: query
description: Namespace of the artifacts
schema:
type: string
default: lockss
- name: limit
in: query
description: The requested maximum number of Archival Unit identifiers per
response
schema:
type: integer
- name: continuationToken
in: query
description: The continuation token of the next page of Archival Unit identifiers
to be returned
schema:
type: string
responses:
'200':
description: The requested Archival Unit identifiers
content:
application/json:
schema:
$ref: '#/components/schemas/auidPageInfo'
default:
description: The resulting error payload.
content:
application/json:
schema:
type: object
/aus/{auid}/bulk:
post:
tags:
- aus
summary: Marks the AUID for bulk artifact transfer
operationId: handleBulkAuOp
parameters:
- name: namespace
in: query
description: Namespace of the artifacts
schema:
type: string
default: lockss
- name: auid
in: path
description: Archival Unit ID
required: true
schema:
type: string
- name: op
in: query
required: true
schema:
type: string
enum:
- start
- finish
responses:
'200':
description: Bulk operation succeeded
content: { }
default:
description: The resulting error payload.
content:
application/json:
schema:
type: object
/aus/{auid}/artifacts:
get:
tags:
- artifacts
summary: Get artifacts in an Archival Unit
description: 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
operationId: getArtifacts
parameters:
- name: namespace
in: query
description: Namespace of the artifacts
schema:
type: string
default: lockss
- name: auid
in: path
description: Identifier of the Archival Unit containing the artifacts
required: true
schema:
type: string
- name: url
in: query
description: The URL contained by the artifacts
schema:
type: string
- name: urlPrefix
in: query
description: The prefix to be matched by the artifact URLs
schema:
type: string
- name: version
in: query
description: The version of the artifact
schema:
type: string
- name: includeUncommitted
in: query
description: Indication of whether uncommitted artifacts should be returned
schema:
type: boolean
- name: limit
in: query
description: The requested maximum number of artifacts per response
schema:
type: integer
- name: continuationToken
in: query
description: The continuation token of the next page of artifacts to be returned
schema:
type: string
responses:
'200':
description: The requested artifacts
content:
application/json:
schema:
$ref: '#/components/schemas/artifactPageInfo'
default:
description: The resulting error payload.
content:
application/json:
schema:
type: object
/aus/{auid}/size:
get:
tags:
- aus
summary: Get the size of Archival Unit artifacts in a namespace
operationId: getArtifactsSize
parameters:
- name: namespace
in: query
description: Namespace of the artifacts
schema:
type: string
default: lockss
- name: auid
in: path
description: Identifier of the Archival Unit containing the artifacts
required: true
schema:
type: string
responses:
200:
description: 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.
content:
application/json:
schema:
$ref: '#/components/schemas/auSize'
default:
description: The resulting error payload.
content:
application/json:
schema:
type: object
/status:
get:
tags:
- status
summary: Get the status of the service
description: Get the status of the service
operationId: getStatus
responses:
'200':
description: The status of the service
content:
application/json:
schema:
$ref: '#/components/schemas/apiStatus'
default:
description: The resulting error payload.
content:
application/json:
schema:
type: object
/wayback/cdx/owb/{namespace}:
get:
tags:
- wayback
summary: Get OpenWayback CDX records
description: Get the OpenWayback CDX records of a URL in a namespace
operationId: getCdxOwb
parameters:
- name: namespace
in: path
description: Namespace of the artifacts
required: true
schema:
type: string
default: lockss
- name: q
in: query
description: 'Query string. Supported fields are url, type (urlqueryprefixquery), offset and limit.'
schema:
type: string
- name: count
in: query
description: "."
schema:
type: integer
- name: start_page
in: query
description: "."
schema:
type: integer
- name: Accept
in: header
description: The Accept header
schema:
type: string
- name: Accept-Encoding
in: header
description: The Accept-Encoding header
schema:
type: string
responses:
'200':
description: The OpenWayback CDX records of the URL in the namespace
content:
application/xml:
schema:
type: string
default:
description: The resulting error payload.
content:
application/json:
schema:
type: object
/wayback/cdx/pywb/{namespace}:
get:
tags:
- wayback
summary: Get PyWayback CDX records
description: Get the PyWayback CDX records of a URL in a namespace
operationId: getCdxPywb
parameters:
- name: namespace
in: path
description: Namespace of the artifacts
required: true
schema:
type: string
default: lockss
- name: url
in: query
description: The URL for which the CDX records are requested
schema:
type: string
- name: limit
in: query
description: "."
schema:
type: integer
- name: matchType
in: query
schema:
type: string
enum:
- exact
- prefix
- host
- domain
- range
- name: sort
in: query
schema:
type: string
enum:
- default
- closest
- reverse
- name: closest
in: query
description: Timestamp for sort=closest mode
schema:
type: string
- name: output
in: query
description: Output format
schema:
type: string
enum:
- cdx
- json
- name: fl
in: query
description: Comma-separated list of fields to include in output
schema:
type: string
- name: Accept
in: header
description: The Accept header
schema:
type: string
- name: Accept-Encoding
in: header
description: The Accept-Encoding header
schema:
type: string
responses:
'200':
description: The PyWayback CDX records of the URL in the namespace
content:
text/plain:
schema:
type: string
default:
description: The resulting error payload.
content:
application/json:
schema:
type: object
/wayback/warcs/{fileName}:
get:
tags:
- wayback
summary: Get a WARC archive
description: Get the contents of a single WARC record as a WARC archive
operationId: getWarcArchive
parameters:
- name: fileName
in: path
description: Name of the WARC archive
required: true
schema:
type: string
- name: Accept
in: header
description: The Accept header
schema:
type: string
- name: Accept-Encoding
in: header
description: The Accept-Encoding header
schema:
type: string
- name: Range
in: header
description: The Range header
schema:
type: string
responses:
'200':
description: The contents of the requested WARC archive
content:
application/warc:
schema:
type: string
format: binary
default:
description: The resulting error payload.
content:
application/json:
schema:
type: object
/checksumalgorithms:
get:
tags:
- repo
summary: Get the supported checksum algorithms
description: Get a list of the names of the supported checksum algorithms
operationId: getSupportedChecksumAlgorithms
responses:
'200':
description: The names of the supported checksum algorithms
content:
application/json:
schema:
type: array
items:
type: string
default:
description: The resulting error payload.
content:
application/json:
schema:
type: object
/repoinfo:
get:
tags:
- repo
summary: Get repository information
description: Get properties of the repository
operationId: getRepositoryInformation
responses:
'200':
description: The repository information
content:
application/json:
schema:
$ref: '#/components/schemas/repositoryInfo'
default:
description: The resulting error payload.
content:
application/json:
schema:
type: object
/repoinfo/storage:
get:
tags:
- repo
summary: Get repository storage information
description: Get properties of the repository storage
operationId: getStorageInfo
responses:
'200':
description: The repository storage information
content:
application/json:
schema:
$ref: '#/components/schemas/storageInfo'
default:
description: The resulting error payload.
content:
application/json:
schema:
type: object
components:
schemas:
errorResult:
type: object
required:
- message
- code
properties:
message:
type: string
code:
type: integer
rootCause:
type: string
importStatus:
type: object
properties:
warcId:
type: string
offset:
type: integer
format: int64
url:
type: string
artifactUuid:
type: string
digest:
type: string
version:
type: integer
status:
type: string
enum:
- OK
- ERROR
- DUPLICATE
- EXCLUDED
statusMessage:
type: string
artifactPageInfo:
required:
- artifacts
- pageInfo
type: object
properties:
artifacts:
description: The artifacts included in the page
type: array
items:
$ref: '#/components/schemas/artifact'
pageInfo:
$ref: '#/components/schemas/pageInfo'
auSize:
type: object
properties:
totalLatestVersions:
type: integer
format: int64
totalAllVersions:
type: integer
format: int64
totalWarcSize:
type: integer
format: int64
artifactProperties:
type: object
properties:
namespace:
type: string
default: lockss
uuid:
type: string
auid:
type: string
uri:
type: string
version:
type: integer
contentLength:
type: integer
format: int64
contentDigest:
type: string
collectionDate:
type: integer
format: int64
storeDate:
type: integer
format: int64
state:
type: string
artifact:
type: object
properties:
committed:
type: boolean
storageUrl:
type: string
namespace:
type: string
default: lockss
uuid:
type: string
auid:
type: string
uri:
type: string
version:
type: integer
contentLength:
type: integer
format: int64
contentDigest:
type: string
collectionDate:
type: integer
format: int64
streamingResponseBody:
type: object
apiStatus:
description: The status information of the service
required:
- apiVersion
- ready
type: object
properties:
apiVersion:
description: The version of the API
type: string
componentName:
description: The name of the component
type: string
componentVersion:
description: The version of the component software
type: string
lockssVersion:
description: The version of the LOCKSS system
type: string
ready:
description: The indication of whether the service is available
type: boolean
serviceName:
description: The name of the service
type: string
readyTime:
description: The time the service last became ready.
type: integer
format: int64
reason:
description: The reason the service isn't ready.
type: string
startupStatus:
description: Enum indicating progress of plugin/AU processing at startup.
type: string
enum:
- NONE
- PLUGINS_CRAWLING
- PLUGINS_COLLECTED
- PLUGINS_LOADING
- PLUGINS_LOADED
- AUS_STARTING
- AUS_STARTED
auidPageInfo:
required:
- auids
- pageInfo
type: object
properties:
auids:
description: The Archival Unit identifiers included in the page
type: array
items:
type: string
pageInfo:
$ref: '#/components/schemas/pageInfo'
pageInfo:
description: The information related to pagination of content
required:
- continuationToken
- curLink
- nextLink
- resultsPerPage
- totalCount
type: object
properties:
totalCount:
description: The total number of results
type: integer
format: int32
resultsPerPage:
description: The number of results per page
type: integer
format: int32
continuationToken:
description: The continuation token
type: string
curLink:
description: The link of the current request
type: string
nextLink:
description: The link of the next request
type: string
repositoryInfo:
description: Information about the repository
required:
- indexInfo
- storeInfo
type: object
properties:
storeInfo:
$ref: '#/components/schemas/storageInfo'
indexInfo:
$ref: '#/components/schemas/storageInfo'
storageInfo:
required:
- avail
- name
- percentUsed
- percentUsedString
- size
- type
- used
description: Information about a repository storage area
type: object
properties:
type:
description: Type of the storage area
type: string
name:
description: Name of the storage area
type: string
size:
description: Size in bytes of the storage area
type: integer
format: int64
used:
description: Used size in bytes of the storage area
type: integer
format: int64
avail:
description: Available size in bytes of the storage area
type: integer
format: int64
percentUsedString:
description: 'Percentage of size used, formatted as a string'
type: string
percentUsed:
description: Percentage of size used
type: number
format: double