frostfs-rest-gw/spec/rest.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:
        - in: header
          name: X-Bearer-Owner-Id
          description: Owner Id (wallet address) that will sign the token
          type: string
          required: true
        - in: header
          description: Token lifetime in epoch
          name: X-Bearer-Lifetime
          type: integer
          default: 100
        - in: body
          name: tokens
          required: true
          description: Bearer token
          schema:
            type: array
            items:
              $ref: '#/definitions/Bearer'
      consumes:
        - application/json
      produces:
        - application/json
      responses:
        200:
          description: Base64 encoded stable binary marshaled bearer token
          schema:
            type: array
            items:
              $ref: '#/definitions/TokenResponse'
        400:
          description: Bad request
          schema:
            $ref: '#/definitions/ErrorResponse'

  /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/ErrorResponse'

  /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/ErrorResponse'

  /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/ErrorResponse'
    delete:
      operationId: deleteObject
      summary: Remove object from NeoFS
      responses:
        200:
          description: Successful deletion
          schema:
            $ref: '#/definitions/SuccessResponse'
        400:
          description: Bad request
          schema:
            $ref: '#/definitions/ErrorResponse'

  /containers:
    put:
      operationId: putContainer
      summary: Create new container in NeoFS
      parameters:
        - $ref: '#/parameters/signatureParam'
        - $ref: '#/parameters/signatureKeyParam'
        - $ref: '#/parameters/signatureScheme'
        - in: query
          name: name-scope-global
          description: Provide this parameter to register container name in NNS service
          type: boolean
          default: false
        - in: body
          name: container
          required: true
          description: Container info
          schema:
            $ref: '#/definitions/ContainerPutInfo'
      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/ErrorResponse'
    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/ErrorResponse'

  /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/ErrorResponse'
    delete:
      operationId: deleteContainer
      summary: Delete container by id
      parameters:
        - $ref: '#/parameters/signatureParam'
        - $ref: '#/parameters/signatureKeyParam'
        - $ref: '#/parameters/signatureScheme'
      responses:
        200:
          description: Successful deletion
          schema:
            $ref: '#/definitions/SuccessResponse'
        400:
          description: Bad request
          schema:
            $ref: '#/definitions/ErrorResponse'
  /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: Successful EACL updating
          schema:
            $ref: '#/definitions/SuccessResponse'
        400:
          description: Bad request
          schema:
            $ref: '#/definitions/ErrorResponse'
    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/ErrorResponse'

definitions:
  Bearer:
    type: object
    properties:
      name:
        type: string
      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:
      name:
        type: string
      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
  ContainerPutInfo:
    description: Represent request body to create container. To specify container name use appropriate property (name provided in attributes will be ignored).
    type: object
    properties:
      containerName:
        type: string
      placementPolicy:
        type: string
      basicAcl:
        type: string
      attributes:
        type: array
        items:
          $ref: '#/definitions/Attribute'
    example:
      containerName: container
      placementPolicy: "REP 3"
      basicAcl: public-read-write
      attributes:
        - key: Custom-Attribute
          value: value
  ContainerInfo:
    type: object
    properties:
      containerId:
        type: string
      containerName:
        type: string
      version:
        type: string
      ownerId:
        type: string
      basicAcl:
        type: string
      placementPolicy:
        type: string
      attributes:
        type: array
        items:
          $ref: '#/definitions/Attribute'
    required:
      - containerId
      - containerName
      - 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/ContainerInfo'
    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
  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
  ErrorType:
    type: string
    enum:
      - GW
      - API
  ErrorResponse:
    type: object
    properties:
      type:
        $ref: '#/definitions/ErrorType'
      code:
        type: integer
      message:
        type: string
    required:
      - type
      - message
  SuccessResponse:
    type: object
    properties:
      success:
        type: boolean
    required:
      - success