frostfs-rest-gw/spec/rest.yaml

578 lines
13 KiB
YAML
Raw Normal View History

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:
type: object
properties:
containerId:
type: string
fileName:
type: string
payload:
type: string
required:
- containerId
- fileName
example:
containerId: 5HZTn5qkRnmgSz9gSrw22CEdPPk6nQhkwf2Mgzyvkikv
fileName: myFile.txt
payload: Y29udGVudCBvZiBmaWxl
consumes:
- application/json
produces:
- application/json
responses:
200:
description: Address of uploaded objects
schema:
type: object
properties:
objectId:
type: string
containerId:
type: string
required:
- objectId
- containerId
example:
objectId: 8N3o7Dtr6T1xteCt6eRwhpmJ7JhME58Hyu1dvaswuTDd
containerId: 5HZTn5qkRnmgSz9gSrw22CEdPPk6nQhkwf2Mgzyvkikv
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 and
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
ContainerBaseInfo:
type: object
properties:
containerId:
type: string
name:
type: string
required:
- containerId
ObjectInfo:
type: object
properties:
containerId:
type: string
objectId:
type: string
ownerId:
type: string
attributes:
type: array
items:
$ref: '#/definitions/Attribute'
required:
- containerId
- objectId
- ownerId
- attributes
example:
containerId: 5HZTn5qkRnmgSz9gSrw22CEdPPk6nQhkwf2Mgzyvkikv
objectId: 8N3o7Dtr6T1xteCt6eRwhpmJ7JhME58Hyu1dvaswuTDd
ownerId: NbUgTSFvPmsRxmGeWpuuGeJUoRoi6PErcM
attribute:
- key: Timestamp
value: "1648810072"
- key: Name
value: object
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