Nasuni ?list Type=2 API

openapi: 3.2.0
info:
  title: Nasuni Data Service (NDS) AWS ?list Type=2 API
  description: "# Overview\n\nWelcome to Nasuni Data Service (NDS) for AWS API Documentation.\n\nThis documentation describes the S3-compatible, read-only endpoints exposed via AWS S3 Object Lambda for accessing data stored in a Nasuni Volume.\n\n## Authentication\n\nThis API sits behind **AWS S3 Object Lambda**. Authenticate exactly as you would to S3:\n\n- **AWS Signature Version 4 (headers)** — Signed requests include:\n  - `Authorization: AWS4-HMAC-SHA256 ...`\n  - `X-Amz-Date: YYYYMMDD'T'HHMMSS'Z'`\n  - `X-Amz-Content-Sha256: UNSIGNED-PAYLOAD`\n  - `X-Amz-Security-Token` (when using temporary credentials)\n\n- **Presigned URLs** — Generated by AWS SDK/CLI. Credentials/signature appear as query params:\n  `X-Amz-Algorithm`, `X-Amz-Credential`, `X-Amz-Date`, `X-Amz-Expires`,\n  `X-Amz-SignedHeaders`, `X-Amz-Signature`, and optional `X-Amz-Security-Token`.\n\n## Available Operations\n* **ListObjects / ListObjectsV2**: List files in a volume.\n* **HeadObject**: Retrieve file metadata and headers.\n* **GetObject**: Download file content; supports single byte-range requests.\n"
  termsOfService: https://www.nasuni.com/legal
  contact:
    name: Nasuni Support
    url: https://www.nasuni.com/support
    email: support@nasuni.com
  license:
    name: Nasuni
    url: https://www.nasuni.com/legal
  version: 1.1.0
security:
- awsSigV4: []
tags:
- name: ?list Type=2
paths:
  /?list-type=2:
    get:
      summary: ListObjectsV2 — list objects in a bucket (V2)
      description: 'Returns a list of objects (files) in the specified bucket (Nasuni volume) using S3 ListObjectsV2 API.


        NDS supports listing objects, using continuation tokens for pagination.


        **Request example**:

        ```

        GET /?list-type=2&prefix=documents/&max-keys=1000&continuation-token=eyJ...

        ```

        '
      operationId: listObjectsV2
      parameters:
      - $ref: '#/components/parameters/AwsAuthorizationHeader'
      - $ref: '#/components/parameters/XAmzDateHeader'
      - $ref: '#/components/parameters/XAmzContentSha256Header'
      - $ref: '#/components/parameters/XAmzSecurityTokenHeader'
      - name: prefix
        in: query
        required: false
        schema:
          type: string
        description: Limits the response to keys that begin with the specified prefix
        example: documents/2025/
      - name: delimiter
        in: query
        required: false
        schema:
          type: string
          maxLength: 1
        description: 'Character used to group keys. Typically set to ''/'' to simulate directory hierarchy.

          When specified, keys containing the delimiter after the prefix are rolled up into CommonPrefixes.

          '
        example: /
      - name: max-keys
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
        description: 'Maximum number of keys to return. If 0, returns an empty result.

          Default and maximum are deployment-configured (commonly 1000).

          '
      - name: continuation-token
        in: query
        required: false
        schema:
          type: string
        description: Continuation token for pagination. Returned from a previous ListObjectsV2 call.
      - name: start-after
        in: query
        required: false
        schema:
          type: string
        description: Returns keys lexicographically after this value (exclusive). Cannot be used with continuation-token.
      - name: fetch-owner
        in: query
        required: false
        schema:
          type: boolean
        description: If true, includes owner information in the response.
      - name: encoding-type
        in: query
        required: false
        schema:
          type: string
          enum:
          - url
        description: Requests URL encoding for object keys in the response.
      responses:
        '200':
          description: Successful ListObjectsV2 response
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/ListBucketResultV2'
              examples:
                listObjectsV2:
                  summary: V2 response (with NextContinuationToken)
                  value: "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<ListBucketResult>\n  <Name>6c19a28d-19cd-4876-ac90-1a2fe3a22426-1</Name>\n  <Prefix></Prefix>\n  <KeyCount>2</KeyCount>\n  <MaxKeys>1000</MaxKeys>\n  <IsTruncated>true</IsTruncated>\n  <NextContinuationToken>eyJDb250aW51YXRpb25Ub2tlbiI6InRydWUifQ==</NextContinuationToken>\n  <Contents>\n    <Key>file1.txt</Key>\n    <LastModified>2025-01-15T10:30:00.000Z</LastModified>\n    <ETag>\"d41d8cd98f00b204e9800998ecf8427e\"</ETag>\n    <Size>1024</Size>\n    <StorageClass>STANDARD</StorageClass>\n  </Contents>\n  <Contents>\n    <Key>file2.pdf</Key>\n    <LastModified>2025-01-16T14:45:00.000Z</LastModified>\n    <ETag>\"e3b0c44298fc1c149afbf4c8996fb924\"</ETag>\n    <Size>2048576</Size>\n    <StorageClass>STANDARD</StorageClass>\n  </Contents>\n</ListBucketResult>\n"
        '403':
          $ref: '#/components/responses/AccessDenied'
        '404':
          $ref: '#/components/responses/NoSuchBucket'
        '424':
          $ref: '#/components/responses/FailedDependency'
        '500':
          $ref: '#/components/responses/InternalError'
        '501':
          $ref: '#/components/responses/NotImplemented'
      tags:
      - ?list Type=2
components:
  schemas:
    Object:
      type: object
      xml:
        name: Contents
      properties:
        Key:
          type: string
          description: Object key (file path)
        LastModified:
          type: string
          format: date-time
          description: Last modification time
        ETag:
          type: string
          description: Entity tag (always quoted)
        Size:
          type: integer
          format: int64
          description: Size in bytes
        StorageClass:
          type: string
          enum:
          - STANDARD
          description: Storage class (always STANDARD for NDS)
    ListBucketResultV2:
      allOf:
      - $ref: '#/components/schemas/ListBucketResultBase'
      - type: object
        properties:
          NextContinuationToken:
            type: string
            description: Token for next page (ListObjectsV2 only)
    Error:
      type: object
      xml:
        name: Error
      properties:
        Code:
          type: string
          description: Error code
        Message:
          type: string
          description: Human-readable error message
        Resource:
          type: string
          description: Resource related to the error
        RequestId:
          type: string
          description: Unique request identifier
    ListBucketResultBase:
      type: object
      xml:
        name: ListBucketResult
      properties:
        Name:
          type: string
          description: Name of the bucket
        Prefix:
          type: string
          description: Keys that begin with the indicated prefix
        Delimiter:
          type: string
          description: Delimiter used for grouping
        MaxKeys:
          type: integer
          description: Maximum number of keys returned
        KeyCount:
          type: integer
          description: Number of keys returned in this result
        IsTruncated:
          type: string
          enum:
          - 'true'
          - 'false'
          description: Whether additional keys exist beyond MaxKeys
        EncodingType:
          type: string
          enum:
          - url
          description: Encoding type applied to object keys
        Contents:
          type: array
          xml:
            wrapped: false
          items:
            $ref: '#/components/schemas/Object'
        CommonPrefixes:
          type: array
          xml:
            wrapped: false
          items:
            type: object
            properties:
              Prefix:
                type: string
  responses:
    AccessDenied:
      description: Access denied or NDS disabled
      content:
        application/xml:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            ndsNotLicensed:
              summary: NDS not available in license
              value: "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<Error>\n  <Code>NDSDisabled</Code>\n  <Message>NDS is not available in your license</Message>\n</Error>\n"
            ndsDisabledConfig:
              summary: NDS disabled in configuration
              value: "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<Error>\n  <Code>NDSDisabled</Code>\n  <Message>NDS is available in your license but is disabled or misconfigured</Message>\n</Error>\n"
    FailedDependency:
      description: Volume not accessible (not shared or missing TOC)
      content:
        application/xml:
          schema:
            $ref: '#/components/schemas/Error'
          example: "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<Error>\n  <Code>FailedDependency</Code>\n  <Message>Volume requires Remote Access enabled and at least one snapshot</Message>\n</Error>\n"
    InternalError:
      description: Internal server error
      content:
        application/xml:
          schema:
            $ref: '#/components/schemas/Error'
          example: "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<Error>\n  <Code>InternalError</Code>\n  <Message>Unexpected error.</Message>\n</Error>\n"
        application/octet-stream:
          schema:
            type: string
            description: May be empty depending on operation.
    NoSuchBucket:
      description: The specified bucket does not exist
      content:
        application/xml:
          schema:
            $ref: '#/components/schemas/Error'
          example: "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<Error>\n  <Code>NoSuchBucket</Code>\n  <Message>The specified bucket does not exist</Message>\n</Error>\n"
    NotImplemented:
      description: Not Implemented - Operation not supported by NDS
      content:
        application/xml:
          schema:
            $ref: '#/components/schemas/Error'
          example: "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<Error>\n  <Code>NotImplemented</Code>\n  <Message>The specified operation is not supported by NDS</Message>\n</Error>\n"
  parameters:
    AwsAuthorizationHeader:
      name: Authorization
      in: header
      required: false
      description: 'AWS Signature Version 4 authorization header.

        Omit when using a presigned URL.

        '
      schema:
        type: string
        example: AWS4-HMAC-SHA256 Credential=AKIA.../20250115/us-east-1/s3/aws4_request, SignedHeaders=host;x-amz-content-sha256;x-amz-date, Signature=0123456789abcdef...
    XAmzSecurityTokenHeader:
      name: X-Amz-Security-Token
      in: header
      required: false
      description: Session token when using temporary credentials (STS/role).
      schema:
        type: string
    XAmzDateHeader:
      name: X-Amz-Date
      in: header
      required: false
      description: ISO8601 timestamp used by SigV4, e.g. 20250115T103000Z. Omit with presigned URLs.
      schema:
        type: string
        example: 20250115T103000Z
    XAmzContentSha256Header:
      name: X-Amz-Content-Sha256
      in: header
      required: false
      description: 'For GET/HEAD, S3 commonly uses `UNSIGNED-PAYLOAD`.

        SDKs set this automatically. Omit with presigned URLs.

        '
      schema:
        type: string
        example: UNSIGNED-PAYLOAD
  securitySchemes:
    awsSigV4:
      type: apiKey
      in: header
      name: Authorization
      description: AWS Signature Version 4. Presigned URLs also supported.