forked from TrueCloudLab/frostfs-rest-gw
706 lines
16 KiB
YAML
706 lines
16 KiB
YAML
swagger: "2.0"
|
|
info:
|
|
title: REST API NeoFS
|
|
description: REST API NeoFS
|
|
version: v1
|
|
|
|
host: localhost:8090
|
|
basePath: /v1
|
|
schemes:
|
|
- http
|
|
# - https
|
|
|
|
securityDefinitions:
|
|
BearerAuth:
|
|
type: apiKey
|
|
in: header
|
|
name: Authorization
|
|
description: Bearer token body to provide with NeoFS request. Must have 'Bearer ' prefix.
|
|
|
|
security:
|
|
- BearerAuth: [ ]
|
|
|
|
parameters:
|
|
signatureParam:
|
|
in: header
|
|
name: X-Bearer-Signature
|
|
description: Base64 encoded signature for bearer token
|
|
type: string
|
|
required: true
|
|
signatureKeyParam:
|
|
in: header
|
|
name: X-Bearer-Signature-Key
|
|
description: Hex encoded the public part of the key that signed the bearer token
|
|
type: string
|
|
required: true
|
|
signatureScheme:
|
|
in: query
|
|
name: walletConnect
|
|
description: Use wallect connect signature scheme or not
|
|
type: boolean
|
|
default: false
|
|
containerId:
|
|
in: path
|
|
name: containerId
|
|
type: string
|
|
required: true
|
|
description: Base58 encoded container id
|
|
objectId:
|
|
in: path
|
|
name: objectId
|
|
type: string
|
|
required: true
|
|
description: Base58 encoded object id
|
|
|
|
paths:
|
|
/auth:
|
|
post:
|
|
operationId: auth
|
|
summary: Form bearer token to futher requests
|
|
security: [ ]
|
|
parameters:
|
|
- $ref: '#/parameters/signatureKeyParam'
|
|
- in: header
|
|
description: Supported operation scope for token
|
|
name: X-Bearer-Scope
|
|
type: string
|
|
enum:
|
|
- object
|
|
- container
|
|
required: true
|
|
- in: header
|
|
description: Token lifetime in epoch
|
|
name: X-Bearer-Lifetime
|
|
type: integer
|
|
default: 100
|
|
- in: body
|
|
name: token
|
|
required: true
|
|
description: Bearer token
|
|
schema:
|
|
$ref: '#/definitions/Bearer'
|
|
consumes:
|
|
- application/json
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
200:
|
|
description: Base64 encoded stable binary marshaled bearer token
|
|
schema:
|
|
$ref: '#/definitions/TokenResponse'
|
|
400:
|
|
description: Bad request
|
|
schema:
|
|
$ref: '#/definitions/Error'
|
|
|
|
/objects:
|
|
parameters:
|
|
- $ref: '#/parameters/signatureParam'
|
|
- $ref: '#/parameters/signatureKeyParam'
|
|
- $ref: '#/parameters/signatureScheme'
|
|
put:
|
|
operationId: putObject
|
|
summary: Upload object to NeoFS
|
|
parameters:
|
|
- in: body
|
|
required: true
|
|
name: object
|
|
description: Object info to upload
|
|
schema:
|
|
$ref: '#/definitions/ObjectUpload'
|
|
consumes:
|
|
- application/json
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
200:
|
|
description: Address of uploaded objects
|
|
schema:
|
|
$ref: '#/definitions/Address'
|
|
400:
|
|
description: Bad request
|
|
schema:
|
|
$ref: '#/definitions/Error'
|
|
|
|
/objects/{containerId}/search:
|
|
parameters:
|
|
- $ref: '#/parameters/signatureParam'
|
|
- $ref: '#/parameters/signatureKeyParam'
|
|
- $ref: '#/parameters/signatureScheme'
|
|
- $ref: '#/parameters/containerId'
|
|
post:
|
|
operationId: searchObjects
|
|
summary: Search objects by filters
|
|
parameters:
|
|
- in: query
|
|
name: offset
|
|
type: integer
|
|
default: 0
|
|
minimum: 0
|
|
description: The number of containers to skip before starting to collect the result set.
|
|
- in: query
|
|
name: limit
|
|
type: integer
|
|
default: 100
|
|
minimum: 1
|
|
maximum: 10000
|
|
description: The numbers of containers to return.
|
|
- in: body
|
|
required: true
|
|
name: searchFilters
|
|
description: Filters to search objects
|
|
schema:
|
|
$ref: '#/definitions/SearchFilters'
|
|
responses:
|
|
200:
|
|
description: List of objects
|
|
schema:
|
|
$ref: '#/definitions/ObjectList'
|
|
400:
|
|
description: Bad request
|
|
schema:
|
|
$ref: '#/definitions/Error'
|
|
|
|
/objects/{containerId}/{objectId}:
|
|
parameters:
|
|
- $ref: '#/parameters/signatureParam'
|
|
- $ref: '#/parameters/signatureKeyParam'
|
|
- $ref: '#/parameters/signatureScheme'
|
|
- $ref: '#/parameters/containerId'
|
|
- $ref: '#/parameters/objectId'
|
|
get:
|
|
operationId: getObjectInfo
|
|
summary: Get object info by address
|
|
parameters:
|
|
- in: query
|
|
name: range-offset
|
|
type: integer
|
|
minimum: 0
|
|
- in: query
|
|
name: range-length
|
|
type: integer
|
|
minimum: 1
|
|
- in: query
|
|
name: max-payload-size
|
|
type: integer
|
|
default: 4194304
|
|
minimum: 0
|
|
maximum: 524288000
|
|
description: |
|
|
Max payload size (in bytes) that can be included in the response.
|
|
If the actual size is greater than this params the payload won't be included in the response.
|
|
responses:
|
|
200:
|
|
description: Object info
|
|
schema:
|
|
$ref: '#/definitions/ObjectInfo'
|
|
400:
|
|
description: Bad request
|
|
schema:
|
|
$ref: '#/definitions/Error'
|
|
delete:
|
|
operationId: deleteObject
|
|
summary: Remove object from NeoFS
|
|
responses:
|
|
204:
|
|
description: Successful deletion
|
|
400:
|
|
description: Bad request
|
|
schema:
|
|
$ref: '#/definitions/Error'
|
|
|
|
/containers:
|
|
put:
|
|
operationId: putContainer
|
|
summary: Create new container in NeoFS
|
|
parameters:
|
|
- $ref: '#/parameters/signatureParam'
|
|
- $ref: '#/parameters/signatureKeyParam'
|
|
- $ref: '#/parameters/signatureScheme'
|
|
- in: query
|
|
name: skip-native-name
|
|
description: Provide this parameter to skip registration container name in NNS service
|
|
type: boolean
|
|
default: false
|
|
- in: body
|
|
name: container
|
|
required: true
|
|
description: Container info
|
|
schema:
|
|
type: object
|
|
properties:
|
|
containerName:
|
|
type: string
|
|
placementPolicy:
|
|
type: string
|
|
basicAcl:
|
|
type: string
|
|
required:
|
|
- containerName
|
|
example:
|
|
containerId: container
|
|
placementPolicy: "REP 3"
|
|
basicAcl: public-read-write
|
|
responses:
|
|
200:
|
|
description: Address of uploaded objects
|
|
schema:
|
|
type: object
|
|
properties:
|
|
containerId:
|
|
type: string
|
|
required:
|
|
- containerId
|
|
example:
|
|
containerId: 5HZTn5qkRnmgSz9gSrw22CEdPPk6nQhkwf2Mgzyvkikv
|
|
400:
|
|
description: Bad request
|
|
schema:
|
|
$ref: '#/definitions/Error'
|
|
get:
|
|
operationId: listContainers
|
|
summary: Get list of containers
|
|
security: [ ]
|
|
parameters:
|
|
- in: query
|
|
name: ownerId
|
|
required: true
|
|
type: string
|
|
description: Base58 encoded owner id
|
|
- in: query
|
|
name: offset
|
|
type: integer
|
|
default: 0
|
|
minimum: 0
|
|
description: The number of containers to skip before starting to collect the result set.
|
|
- in: query
|
|
name: limit
|
|
type: integer
|
|
default: 100
|
|
minimum: 1
|
|
maximum: 10000
|
|
description: The numbers of containers to return.
|
|
responses:
|
|
200:
|
|
description: Containers info
|
|
schema:
|
|
$ref: '#/definitions/ContainerList'
|
|
400:
|
|
description: Bad request
|
|
schema:
|
|
$ref: '#/definitions/Error'
|
|
|
|
/containers/{containerId}:
|
|
parameters:
|
|
- $ref: '#/parameters/containerId'
|
|
get:
|
|
operationId: getContainer
|
|
summary: Get container by id
|
|
security: [ ]
|
|
responses:
|
|
200:
|
|
description: Container info
|
|
schema:
|
|
$ref: '#/definitions/ContainerInfo'
|
|
400:
|
|
description: Bad request
|
|
schema:
|
|
$ref: '#/definitions/Error'
|
|
delete:
|
|
operationId: deleteContainer
|
|
summary: Delete container by id
|
|
parameters:
|
|
- $ref: '#/parameters/signatureParam'
|
|
- $ref: '#/parameters/signatureKeyParam'
|
|
- $ref: '#/parameters/signatureScheme'
|
|
responses:
|
|
204:
|
|
description: Successul deletion
|
|
400:
|
|
description: Bad request
|
|
schema:
|
|
$ref: '#/definitions/Error'
|
|
/containers/{containerId}/eacl:
|
|
parameters:
|
|
- $ref: '#/parameters/containerId'
|
|
put:
|
|
operationId: putContainerEACL
|
|
summary: Set container EACL by id
|
|
parameters:
|
|
- $ref: '#/parameters/signatureParam'
|
|
- $ref: '#/parameters/signatureKeyParam'
|
|
- $ref: '#/parameters/signatureScheme'
|
|
- in: body
|
|
name: eacl
|
|
required: true
|
|
description: EACL for container
|
|
schema:
|
|
$ref: '#/definitions/Eacl'
|
|
responses:
|
|
200:
|
|
description: Successfule EACL upading
|
|
400:
|
|
description: Bad request
|
|
schema:
|
|
$ref: '#/definitions/Error'
|
|
get:
|
|
operationId: getContainerEACL
|
|
summary: Get container EACL by id
|
|
security: [ ]
|
|
responses:
|
|
200:
|
|
description: Container EACL information
|
|
schema:
|
|
$ref: '#/definitions/Eacl'
|
|
400:
|
|
description: Bad request
|
|
schema:
|
|
$ref: '#/definitions/Error'
|
|
|
|
definitions:
|
|
Bearer:
|
|
type: object
|
|
properties:
|
|
object:
|
|
type: array
|
|
items:
|
|
$ref: '#/definitions/Record'
|
|
container:
|
|
$ref: '#/definitions/Rule'
|
|
Record:
|
|
type: object
|
|
properties:
|
|
action:
|
|
$ref: '#/definitions/Action'
|
|
operation:
|
|
$ref: '#/definitions/Operation'
|
|
filters:
|
|
type: array
|
|
items:
|
|
$ref: '#/definitions/Filter'
|
|
targets:
|
|
type: array
|
|
items:
|
|
$ref: '#/definitions/Target'
|
|
required:
|
|
- action
|
|
- operation
|
|
- filters
|
|
- targets
|
|
example:
|
|
operation: GET
|
|
action: ALLOW
|
|
filters: [ ]
|
|
targets:
|
|
- role: OTHERS
|
|
keys: [ ]
|
|
Action:
|
|
type: string
|
|
enum:
|
|
- ALLOW
|
|
- DENY
|
|
Operation:
|
|
type: string
|
|
enum:
|
|
- GET
|
|
- HEAD
|
|
- PUT
|
|
- DELETE
|
|
- SEARCH
|
|
- RANGE
|
|
- RANGEHASH
|
|
Filter:
|
|
type: object
|
|
properties:
|
|
headerType:
|
|
$ref: '#/definitions/HeaderType'
|
|
matchType:
|
|
$ref: '#/definitions/MatchType'
|
|
key:
|
|
type: string
|
|
value:
|
|
type: string
|
|
required:
|
|
- headerType
|
|
- matchType
|
|
- key
|
|
- value
|
|
example:
|
|
headerType: OBJECT
|
|
matchType: STRING_NOT_EQUAL
|
|
key: FileName
|
|
value: myfile
|
|
HeaderType:
|
|
type: string
|
|
enum:
|
|
- REQUEST
|
|
- OBJECT
|
|
- SERVICE
|
|
MatchType:
|
|
type: string
|
|
enum:
|
|
- STRING_EQUAL
|
|
- STRING_NOT_EQUAL
|
|
Target:
|
|
type: object
|
|
properties:
|
|
role:
|
|
$ref: '#/definitions/Role'
|
|
keys:
|
|
type: array
|
|
items:
|
|
type: string
|
|
required:
|
|
- role
|
|
- keys
|
|
example:
|
|
role: USER
|
|
keys:
|
|
- 021dc56fc6d81d581ae7605a8e00e0e0bab6cbad566a924a527339475a97a8e38e
|
|
Role:
|
|
type: string
|
|
enum:
|
|
- USER
|
|
- SYSTEM
|
|
- OTHERS
|
|
Rule:
|
|
type: object
|
|
properties:
|
|
verb:
|
|
$ref: '#/definitions/Verb'
|
|
containerId:
|
|
type: string
|
|
required:
|
|
- verb
|
|
Verb:
|
|
type: string
|
|
enum:
|
|
- PUT
|
|
- DELETE
|
|
- SETEACL
|
|
TokenResponse:
|
|
type: object
|
|
properties:
|
|
type:
|
|
$ref: '#/definitions/TokenType'
|
|
token:
|
|
type: string
|
|
required:
|
|
- type
|
|
- token
|
|
example:
|
|
- type: object
|
|
token: sometoken-todo-add
|
|
- type: container
|
|
token: ChCpanIBJCpJuJz42KOmGMSnEhsKGTWquaX2Lq6GhhO4faOYkLD0f9WkXuYJlq4aBAhnGAMiIQJgFcIEghQB5lq3AJZOVswInwc1IGhlQ7NCUh4DFO3UATIECAEQAQ==
|
|
TokenType:
|
|
type: string
|
|
enum:
|
|
- object
|
|
- container
|
|
ContainerInfo:
|
|
type: object
|
|
properties:
|
|
containerId:
|
|
type: string
|
|
version:
|
|
type: string
|
|
ownerId:
|
|
type: string
|
|
basicAcl:
|
|
type: string
|
|
placementPolicy:
|
|
type: string
|
|
attributes:
|
|
type: array
|
|
items:
|
|
$ref: '#/definitions/Attribute'
|
|
required:
|
|
- containerId
|
|
- version
|
|
- ownerId
|
|
- basicAcl
|
|
- placementPolicy
|
|
- attributes
|
|
example:
|
|
containerId: 5HZTn5qkRnmgSz9gSrw22CEdPPk6nQhkwf2Mgzyvkikv
|
|
version: "2.11"
|
|
ownerId: NbUgTSFvPmsRxmGeWpuuGeJUoRoi6PErcM
|
|
basicAcl: "0x1fbf9fff"
|
|
placementPolicy: "REP 2"
|
|
attribute:
|
|
- key: Timestamp
|
|
value: "1648810072"
|
|
- key: Name
|
|
value: container
|
|
ContainerList:
|
|
type: object
|
|
properties:
|
|
size:
|
|
type: integer
|
|
containers:
|
|
type: array
|
|
items:
|
|
$ref: '#/definitions/ContainerBaseInfo'
|
|
required:
|
|
- size
|
|
- containers
|
|
SearchFilters:
|
|
type: object
|
|
properties:
|
|
filters:
|
|
type: array
|
|
items:
|
|
$ref: '#/definitions/SearchFilter'
|
|
required:
|
|
- filters
|
|
SearchFilter:
|
|
type: object
|
|
properties:
|
|
key:
|
|
type: string
|
|
value:
|
|
type: string
|
|
match:
|
|
$ref: '#/definitions/SearchMatch'
|
|
required:
|
|
- key
|
|
- value
|
|
- match
|
|
SearchMatch:
|
|
type: string
|
|
enum:
|
|
- MatchStringEqual
|
|
- MatchStringNotEqual
|
|
- MatchNotPresent
|
|
- MatchCommonPrefix
|
|
ContainerBaseInfo:
|
|
type: object
|
|
properties:
|
|
containerId:
|
|
type: string
|
|
name:
|
|
type: string
|
|
required:
|
|
- containerId
|
|
ObjectList:
|
|
type: object
|
|
properties:
|
|
size:
|
|
type: integer
|
|
objects:
|
|
type: array
|
|
items:
|
|
$ref: '#/definitions/ObjectBaseInfo'
|
|
required:
|
|
- size
|
|
- objects
|
|
ObjectBaseInfo:
|
|
type: object
|
|
properties:
|
|
address:
|
|
$ref: '#/definitions/Address'
|
|
name:
|
|
type: string
|
|
required:
|
|
- address
|
|
ObjectUpload:
|
|
type: object
|
|
properties:
|
|
containerId:
|
|
type: string
|
|
fileName:
|
|
type: string
|
|
payload:
|
|
type: string
|
|
attributes:
|
|
type: array
|
|
items:
|
|
$ref: '#/definitions/Attribute'
|
|
required:
|
|
- containerId
|
|
- fileName
|
|
example:
|
|
containerId: 5HZTn5qkRnmgSz9gSrw22CEdPPk6nQhkwf2Mgzyvkikv
|
|
fileName: myFile.txt
|
|
payload: Y29udGVudCBvZiBmaWxl
|
|
attributes:
|
|
- key: User-Attribute
|
|
value: some-value
|
|
ObjectInfo:
|
|
type: object
|
|
properties:
|
|
containerId:
|
|
type: string
|
|
objectId:
|
|
type: string
|
|
ownerId:
|
|
type: string
|
|
attributes:
|
|
type: array
|
|
items:
|
|
$ref: '#/definitions/Attribute'
|
|
objectSize:
|
|
type: integer
|
|
description: Object full payload size
|
|
payloadSize:
|
|
type: integer
|
|
description: Payload size in response
|
|
payload:
|
|
type: string
|
|
description: Base64 encoded object payload
|
|
required:
|
|
- containerId
|
|
- objectId
|
|
- ownerId
|
|
- attributes
|
|
- objectSize
|
|
- payloadSize
|
|
example:
|
|
containerId: 5HZTn5qkRnmgSz9gSrw22CEdPPk6nQhkwf2Mgzyvkikv
|
|
objectId: 8N3o7Dtr6T1xteCt6eRwhpmJ7JhME58Hyu1dvaswuTDd
|
|
ownerId: NbUgTSFvPmsRxmGeWpuuGeJUoRoi6PErcM
|
|
attribute:
|
|
- key: Timestamp
|
|
value: "1648810072"
|
|
- key: Name
|
|
value: object
|
|
Address:
|
|
type: object
|
|
properties:
|
|
containerId:
|
|
type: string
|
|
objectId:
|
|
type: string
|
|
required:
|
|
- containerId
|
|
- objectId
|
|
example:
|
|
objectId: 8N3o7Dtr6T1xteCt6eRwhpmJ7JhME58Hyu1dvaswuTDd
|
|
containerId: 5HZTn5qkRnmgSz9gSrw22CEdPPk6nQhkwf2Mgzyvkikv
|
|
Eacl:
|
|
type: object
|
|
properties:
|
|
containerId:
|
|
type: string
|
|
readOnly: true
|
|
records:
|
|
type: array
|
|
items:
|
|
$ref: '#/definitions/Record'
|
|
required:
|
|
- records
|
|
Attribute:
|
|
type: object
|
|
properties:
|
|
key:
|
|
type: string
|
|
value:
|
|
type: string
|
|
required:
|
|
- key
|
|
- value
|
|
Principal:
|
|
type: string
|
|
Error:
|
|
type: string
|