frostfs-rest-gw/spec/rest.yaml

swagger: "2.0"
info:
  title: REST API NeoFS
  description: REST API for native integration with NeoFS.
  version: v1

host: localhost:8090
basePath: /v1
schemes:
  - http

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 wallet connect signature scheme or native NeoFS signature.
    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:
    options:
      operationId: optionsAuth
      security: [ ]
      responses:
        200:
          description: CORS
          headers:
            Access-Control-Allow-Origin:
              type: string
            Access-Control-Allow-Headers:
              type: string
    post:
      operationId: auth
      summary: Form bearer token to further 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 tokens to form.
          schema:
            type: array
            items:
              $ref: '#/definitions/Bearer'
      consumes:
        - application/json
      produces:
        - application/json
      responses:
        200:
          description: Base64 encoded stable binary marshaled bearer token.
          headers:
            Access-Control-Allow-Origin:
              type: string
          schema:
            type: array
            items:
              $ref: '#/definitions/TokenResponse'
        400:
          description: Bad request
          schema:
            $ref: '#/definitions/ErrorResponse'

  /accounting/balance/{address}:
    get:
      operationId: getBalance
      summary: Get balance in NeoFS
      description: Getting balance of provided wallet address in NeoFS.
      security: [ ]
      parameters:
        - in: path
          name: address
          type: string
          required: true
          description: Base58 encoded wallet address.
      produces:
        - application/json
      responses:
        200:
          description: Balance of address in NeoFS
          schema:
            $ref: '#/definitions/Balance'
          headers:
            Access-Control-Allow-Origin:
              type: string
        400:
          description: Bad request
          schema:
            $ref: '#/definitions/ErrorResponse'

  /objects:
    options:
      operationId: optionsObjectsPut
      security: [ ]
      responses:
        200:
          description: CORS
          headers:
            Access-Control-Allow-Origin:
              type: string
            Access-Control-Allow-Headers:
              type: string
            Access-Control-Allow-Methods:
              type: string
    put:
      operationId: putObject
      summary: Upload object to NeoFS
      parameters:
        - $ref: '#/parameters/signatureParam'
        - $ref: '#/parameters/signatureKeyParam'
        - $ref: '#/parameters/signatureScheme'
        - in: body
          required: true
          name: object
          description: Object info to upload
          schema:
            $ref: '#/definitions/ObjectUpload'
      consumes:
        - application/json
      produces:
        - application/json
      responses:
        200:
          headers:
            Access-Control-Allow-Origin:
              type: string
          description: Address of uploaded objects
          schema:
            $ref: '#/definitions/Address'
        400:
          description: Bad request
          schema:
            $ref: '#/definitions/ErrorResponse'

  /objects/{containerId}/search:
    parameters:
      - $ref: '#/parameters/containerId'
    options:
      operationId: optionsObjectsSearch
      security: []
      responses:
        200:
          description: Base64 encoded stable binary marshaled bearer token.
          headers:
            Access-Control-Allow-Origin:
              type: string
            Access-Control-Allow-Headers:
              type: string
    post:
      operationId: searchObjects
      summary: Search objects by filters
      parameters:
        - $ref: '#/parameters/signatureParam'
        - $ref: '#/parameters/signatureKeyParam'
        - $ref: '#/parameters/signatureScheme'
        - 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:
          headers:
            Access-Control-Allow-Origin:
              type: string
          description: List of objects
          schema:
            $ref: '#/definitions/ObjectList'
        400:
          description: Bad request
          schema:
            $ref: '#/definitions/ErrorResponse'

  /objects/{containerId}/{objectId}:
    parameters:
      - $ref: '#/parameters/containerId'
      - $ref: '#/parameters/objectId'
    options:
      operationId: optionsObjectsGetDelete
      security: [ ]
      responses:
        200:
          description: CORS
          headers:
            Access-Control-Allow-Origin:
              type: string
            Access-Control-Allow-Headers:
              type: string
            Access-Control-Allow-Methods:
              type: string
    get:
      operationId: getObjectInfo
      summary: Get object info by address
      parameters:
        - $ref: '#/parameters/signatureParam'
        - $ref: '#/parameters/signatureKeyParam'
        - $ref: '#/parameters/signatureScheme'
        - in: query
          name: range-offset
          type: integer
          minimum: 0
          description: Range offset to start reading data.
        - in: query
          name: range-length
          type: integer
          minimum: 1
          description: Length of data range.
        - 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:
          headers:
            Access-Control-Allow-Origin:
              type: string
          description: Object info
          schema:
            $ref: '#/definitions/ObjectInfo'
        400:
          description: Bad request
          schema:
            $ref: '#/definitions/ErrorResponse'
    delete:
      operationId: deleteObject
      summary: Remove object from NeoFS
      parameters:
        - $ref: '#/parameters/signatureParam'
        - $ref: '#/parameters/signatureKeyParam'
        - $ref: '#/parameters/signatureScheme'
      responses:
        200:
          headers:
            Access-Control-Allow-Origin:
              type: string
          description: Successful deletion.
          schema:
            $ref: '#/definitions/SuccessResponse'
        400:
          description: Bad request.
          schema:
            $ref: '#/definitions/ErrorResponse'

  /containers:
    options:
      operationId: optionsContainersPutList
      security: [ ]
      responses:
        200:
          description: CORS
          headers:
            Access-Control-Allow-Origin:
              type: string
            Access-Control-Allow-Headers:
              type: string
            Access-Control-Allow-Methods:
              type: string
    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:
          headers:
            Access-Control-Allow-Origin:
              type: string
          description: Identifier of the created container.
          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:
          headers:
            Access-Control-Allow-Origin:
              type: string
          description: Containers info.
          schema:
            $ref: '#/definitions/ContainerList'
        400:
          description: Bad request.
          schema:
            $ref: '#/definitions/ErrorResponse'

  /containers/{containerId}:
    parameters:
      - $ref: '#/parameters/containerId'
    options:
      operationId: optionsContainersGetDelete
      security: [ ]
      responses:
        200:
          description: CORS
          headers:
            Access-Control-Allow-Origin:
              type: string
            Access-Control-Allow-Headers:
              type: string
            Access-Control-Allow-Methods:
              type: string
    get:
      operationId: getContainer
      summary: Get container by id
      security: [ ]
      responses:
        200:
          headers:
            Access-Control-Allow-Origin:
              type: string
          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:
          headers:
            Access-Control-Allow-Origin:
              type: string
          description: Successful deletion.
          schema:
            $ref: '#/definitions/SuccessResponse'
        400:
          description: Bad request.
          schema:
            $ref: '#/definitions/ErrorResponse'

  /containers/{containerId}/eacl:
    parameters:
      - $ref: '#/parameters/containerId'
    options:
      operationId: optionsContainersEACL
      security: [ ]
      responses:
        200:
          description: CORS
          headers:
            Access-Control-Allow-Origin:
              type: string
            Access-Control-Allow-Headers:
              type: string
            Access-Control-Allow-Methods:
              type: string
    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:
          headers:
            Access-Control-Allow-Origin:
              type: string
          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:
          headers:
            Access-Control-Allow-Origin:
              type: string
          description: Container EACL information.
          schema:
            $ref: '#/definitions/Eacl'
        400:
          description: Bad request.
          schema:
            $ref: '#/definitions/ErrorResponse'

definitions:
  Bearer:
    description: Bearer token that is expected to be formed.
    type: object
    properties:
      name:
        type: string
      object:
        type: array
        items:
          $ref: '#/definitions/Record'
      container:
        $ref: '#/definitions/Rule'
    example:
      - name: my-bearer-token
        object:
          - operation: GET
            action: ALLOW
            filters: [ ]
            targets:
              - role: OTHERS
                keys: [ ]
      - name: "my token to create container"
        container:
          verb: PUT
  Record:
    description: A single NeoFS EACL rule.
    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:
    description: Rule execution result action in NeoFS EACL. Either allows or denies access if the rule's filters match.
    type: string
    enum:
      - ALLOW
      - DENY
  Operation:
    description: Request's operation type to match in NeoFS EACL if the rule is applicable to a particular request.
    type: string
    enum:
      - GET
      - HEAD
      - PUT
      - DELETE
      - SEARCH
      - RANGE
      - RANGEHASH
  Filter:
    description: Filter in NeoFS EACL to check particular properties of the request or the object.
    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:
    description: Enumeration of possible sources of Headers to apply filters in NeoFS EACL.
    type: string
    enum:
      - REQUEST
      - OBJECT
      - SERVICE
  MatchType:
    description: Match type in NeoFS EACL filter.
    type: string
    enum:
      - STRING_EQUAL
      - STRING_NOT_EQUAL
  Target:
    description: Target to apply the ACL rule. Can be a subject's role class or a list of public keys to match.
    type: object
    properties:
      role:
        $ref: '#/definitions/Role'
      keys:
        type: array
        items:
          type: string
    required:
      - role
      - keys
    example:
      role: USER
      keys:
        - 021dc56fc6d81d581ae7605a8e00e0e0bab6cbad566a924a527339475a97a8e38e
  Role:
    description: Role for target in EACL.
    type: string
    enum:
      - USER
      - SYSTEM
      - OTHERS
  Rule:
    description: Container session token rule.
    type: object
    properties:
      verb:
        $ref: '#/definitions/Verb'
      containerId:
        type: string
    required:
      - verb
    example:
      verb: DELETE
      containerId: 6jvKJCQr6e47Yx8SsbSN3fNgzroUJVkY66Q9wqxYcAjc
  Verb:
    description: Verb that describes the allowed container operation for token.
    type: string
    enum:
      - PUT
      - DELETE
      - SETEACL
  TokenResponse:
    description: Base64 encoded marshaled token (for container or for object operations).
    type: object
    properties:
      name:
        type: string
      type:
        $ref: '#/definitions/TokenType'
      token:
        type: string
    required:
      - type
      - token
    example:
      - type: object
        token: ClYKBAgCEA0aCAgDEAEiAggDGggIARACIgIIAxoICAIQAiICCAMaCAgDEAIiAggDGggIBBACIgIIAxoICAUQAiICCAMaCAgGEAIiAggDGggIBxACIgIIAxIbChk182WEDFuAqq3nssrGOaH0NK0ZhzF8bu+YGgQIaBgE
      - type: container
        token: ChCpanIBJCpJuJz42KOmGMSnEhsKGTWquaX2Lq6GhhO4faOYkLD0f9WkXuYJlq4aBAhnGAMiIQJgFcIEghQB5lq3AJZOVswInwc1IGhlQ7NCUh4DFO3UATIECAEQAQ==
  TokenType:
    description: Type of token.
    type: string
    enum:
      - object
      - container
  ContainerPutInfo:
    description: 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:
    description: Information about container.
    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
      containerName: container
      version: "2.11"
      ownerId: NbUgTSFvPmsRxmGeWpuuGeJUoRoi6PErcM
      basicAcl: "0x1fbf9fff"
      placementPolicy: "REP 2"
      attribute:
        - key: Timestamp
          value: "1648810072"
        - key: Name
          value: container
  ContainerList:
    description: List of containers info
    type: object
    properties:
      size:
        type: integer
      containers:
        type: array
        items:
          $ref: '#/definitions/ContainerInfo'
    required:
      - size
      - containers
    example:
      size: 2
      containers:
        - containerId: 5HZTn5qkRnmgSz9gSrw22CEdPPk6nQhkwf2Mgzyvkikv
          containerName: container
          version: "2.11"
          ownerId: NbUgTSFvPmsRxmGeWpuuGeJUoRoi6PErcM
          basicAcl: "0x1fbf9fff"
          placementPolicy: "REP 2"
          attribute:
            - key: Timestamp
              value: "1648810072"
            - key: Name
              value: container
        - containerId: FsE7HLQBBYc2WFJzuTXMcpspDEmwUxsD5YmNb2r25uUu
          containerName: container2
          version: "2.11"
          ownerId: NbUgTSFvPmsRxmGeWpuuGeJUoRoi6PErcM
          basicAcl: "0x1fbf9fff"
          placementPolicy: "REP 1"
          attribute:
            - key: Name
              value: container2
  SearchFilters:
    description: List of SearchFilter elements.
    type: object
    properties:
      filters:
        type: array
        items:
          $ref: '#/definitions/SearchFilter'
    required:
      - filters
    example:
      filters:
        - key: FileName
          value: some/prefix
          match: MatchCommonPrefix
        - key: CustomAttribute
          value: tag-value
          match: MatchStringEqual
  SearchFilter:
    description: Search filter to find objects.
    type: object
    properties:
      key:
        type: string
      value:
        type: string
      match:
        $ref: '#/definitions/SearchMatch'
    required:
      - key
      - value
      - match
    example:
      key: FileName
      value: object-name
      match: MatchStringEqual
  SearchMatch:
    description: Search match type.
    type: string
    enum:
      - MatchStringEqual
      - MatchStringNotEqual
      - MatchNotPresent
      - MatchCommonPrefix
  ObjectList:
    description: List of objects.
    type: object
    properties:
      size:
        type: integer
      objects:
        type: array
        items:
          $ref: '#/definitions/ObjectBaseInfo'
    required:
      - size
      - objects
    example:
      size: 2
      objects:
        - name: "/my/object/name"
          address:
            objectId: 8N3o7Dtr6T1xteCt6eRwhpmJ7JhME58Hyu1dvaswuTDd
            containerId: 5HZTn5qkRnmgSz9gSrw22CEdPPk6nQhkwf2Mgzyvkikv
        - name: "/my/object/some/other/name"
          address:
            objectId: 3GbmMWusaWgMHokWui2zDunxMTzButuQMVLbtL3cDn8s
            containerId: 5HZTn5qkRnmgSz9gSrw22CEdPPk6nQhkwf2Mgzyvkikv
  ObjectBaseInfo:
    description: Basic object information.
    type: object
    properties:
      address:
        $ref: '#/definitions/Address'
      name:
        type: string
    required:
      - address
    example:
      name: "/my/object/name"
      address:
        objectId: 8N3o7Dtr6T1xteCt6eRwhpmJ7JhME58Hyu1dvaswuTDd
        containerId: 5HZTn5qkRnmgSz9gSrw22CEdPPk6nQhkwf2Mgzyvkikv
  ObjectUpload:
    description: Request body to create object.
    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:
    description: Object information.
    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:
    description: Address of the object in NeoFS.
    type: object
    properties:
      containerId:
        type: string
      objectId:
        type: string
    required:
      - containerId
      - objectId
    example:
      objectId: 8N3o7Dtr6T1xteCt6eRwhpmJ7JhME58Hyu1dvaswuTDd
      containerId: 5HZTn5qkRnmgSz9gSrw22CEdPPk6nQhkwf2Mgzyvkikv
  Eacl:
    description: EACL NeoFS table.
    type: object
    properties:
      containerId:
        type: string
        readOnly: true
      records:
        type: array
        items:
          $ref: '#/definitions/Record'
    required:
      - records
    example:
      containerId: 5HZTn5qkRnmgSz9gSrw22CEdPPk6nQhkwf2Mgzyvkikv
      records:
        - action: GET
          operation: ALLOW
          filters:
            - headerType: OBJECT
              matchType: STRING_EQUAL
              key: FileName
              value: myfile
          targets:
            - role: OTHERS
  Attribute:
    description: Attribute is a pair of strings that can be attached to a container or an object.
    type: object
    properties:
      key:
        type: string
      value:
        type: string
    required:
      - key
      - value
    example:
      key: "User-Defined-Tag"
      value: "tag value"
  Principal:
    type: string
  Balance:
    type: object
    properties:
      address:
        type: string
      value:
        type: string
      precision:
        type: integer
    required:
      - address
      - value
      - precision
  ErrorType:
    description: Error type. Allow determine source of the error.
    type: string
    enum:
      - GW
      - API
  ErrorResponse:
    description: Error response.
    type: object
    properties:
      type:
        $ref: '#/definitions/ErrorType'
      code:
        type: integer
      message:
        type: string
    required:
      - type
      - message
    example:
      type: API
      code: 1024
      message: "incomplete object PUT by placement"
  SuccessResponse:
    description: Success response.
    type: object
    properties:
      success:
        type: boolean
    required:
      - success
    example:
      success: true