api.raml

#%RAML 1.0
title: File Storage
version: v2.0.0
baseUri:
protocols: [ HTTPS ]

description: |
  A file storage API that mimics Amazon S3's functionality.

mediaType: application/json

types:
  ErrorResponse:
    type: object
    properties:
      message: string
      code: number

  Bucket:
    type: object
    properties:
      name: string
      creationDate: date-time
      numberOfObjects: number
      size: number

  Buckets:
    type: array
    items: Bucket

  ObjectMetadata:
    type: object
    properties:
      key: string
      size: number
      lastModified: date-time
      type: string

  ObjectList:
    type: object
    properties:
      bucketName: string
      objects:
        type: array
        items: ObjectMetadata

  UploadResponse:
    type: object
    properties:
      key: string
      bucket: string

  UploadMultipleResponse:
    type: object
    properties:
      message: string
      files:
        type: array
        items: string

  RemoveMultipleResponse:
    type: object
    properties:
      message: string
      removedObjects:
        type: array
        items: ObjectMetadata

/buckets:
  get:
    description: List all buckets for the authenticated user.
    responses:
      200:
        body:
          application/json:
            type: Buckets
            example: |
              [
                { "name": "photos", "creationDate": "2024-01-01T12:00:00Z", "numberOfObjects": 10, "size": 20480 },
                { "name": "documents", "creationDate": "2024-02-01T08:30:00Z", "numberOfObjects": 5, "size": 10240 }
              ]
      400:
        body:
          application/json:
            type: ErrorResponse
            example: |
              {
                "message": "Invalid parameters",
                "code": 400
              }

  post:
    description: Create a new bucket.
    body:
      application/json:
        example: |
          { "name": "my-new-bucket" }
    responses:
      201:
        body:
          application/json:
            example: |
              {
                "name": "my-new-bucket",
                "creationDate": "2024-03-01T09:15:00Z",
                "numberOfObjects": 0,
                "size": 0
              }
      400:
        body:
          application/json:
            type: ErrorResponse
            example: |
              {
                "message": "Bucket name already exists",
                "code": 400
              }

  /{bucketName}:
    uriParameters:
      bucketName:
        description: The name of the bucket.
        type: string
        required: true

    get:
      description: Get information about a specific bucket or list objects in that bucket.
      queryParameters:
        listObjects?:
          description: If set to true, returns a list of objects in the bucket.
          type: boolean
          default: false
        prefix?:
          description: Filter the object list by this prefix (i.e., a "directory").
          type: string
          example: "photos/2024/event1/"
      responses:
        200:
          body:
            application/json:
              oneOf:
                - type: Bucket      # When listObjects is false
                - type: ObjectList  # When listObjects is true
          examples:
            bucketInfo:
              value: |
                {
                  "name": "photos",
                  "creationDate": "2024-01-01T12:00:00Z",
                  "numberOfObjects": 10,
                  "size": 20480
                }
            objectList:
              value: |
                {
                  "bucketName": "photos",
                  "objects": [
                    {
                      "key": "2024/event1/image1.jpg",
                      "size": 2048,
                      "lastModified": "2024-01-10T10:00:00Z",
                      "type": "image/jpeg"
                    },
                    {
                      "key": "2024/event2/image1.jpg",
                      "size": 4096,
                      "lastModified": "2024-01-15T08:00:00Z",
                      "type": "image/jpeg"
                    }
                  ]
                }
        404:
          body:
            application/json:
              type: ErrorResponse
              example: |
                {
                  "message": "Bucket not found",
                  "code": 404
                }

    delete:
      description: Delete the specified bucket. The bucket must be empty.
      responses:
        204:
          description: Bucket successfully deleted. No content returned.
        400:
          body:
            application/json:
              type: ErrorResponse
              example: |
                {
                  "message": "Bucket is not empty",
                  "code": 400
                }
        404:
          body:
            application/json:
              type: ErrorResponse
              example: |
                {
                  "message": "Bucket not found",
                  "code": 404
                }

    /upload-multiple:
      uriParameters:
        bucketName:
          description: The name of the bucket.
          type: string
          required: true
      post:
        description: >
          Upload multiple files under the same prefix (if provided).
          Each file is stored as an individual object with a final key of `{prefix}{filename}`.
        queryParameters:
          prefix?:
            description: The directory-like path to store all files under, e.g. `photos/2024/event1/`
            type: string
            example: "photos/2024/event1/"
            default: ""
        body:
          multipart/form-data:
            formParameters:
              files:
                description: A single key "files" containing one or more files to be uploaded.
                type: file
                required: true
                repeat: true
        responses:
          200:
            body:
              application/json:
                type: UploadMultipleResponse
                example: |
                  {
                    "message": "Files uploaded successfully",
                    "files": [
                      "photos/2024/event1/file1.jpg",
                      "photos/2024/event1/document.pdf"
                    ]
                  }
          400:
            body:
              application/json:
                type: ErrorResponse
                example: |
                  {
                    "message": "Invalid file data or request parameters",
                    "code": 400
                  }
          404:
            body:
              application/json:
                type: ErrorResponse
                example: |
                  {
                    "message": "Bucket not found",
                    "code": 404
                  }

    /remove-multiple:
      uriParameters:
        bucketName:
          description: The name of the bucket.
          type: string
          required: true
      delete:
        description: Delete multiple objects in the specified bucket with keys starting with the given prefix.
        queryParameters:
          prefix?:
            description: Filter objects by this prefix (e.g., `photos/2024/event1/`).
            type: string
            example: "photos/2024/event1/"
            default: ""
        responses:
          200:
            body:
              application/json:
                type: RemoveMultipleResponse
                example: |
                  {
                    "message": "Objects removed successfully",
                    "removedObjects": [
                      {
                        "key": "photos/2024/event1/image1.jpg",
                        "size": 2048,
                        "lastModified": "2024-01-10T10:00:00Z",
                        "type": "image/jpeg"
                      },
                      {
                        "key": "photos/2024/event1/document.pdf",
                        "size": 10240,
                        "lastModified": "2024-01-12T10:00:00Z",
                        "type": "application/pdf"
                      }
                    ]
                  }
          400:
            body:
              application/json:
                type: ErrorResponse
                example: |
                  {
                    "message": "Invalid request parameters",
                    "code": 400
                  }
          404:
            body:
              application/json:
                type: ErrorResponse
                example: |
                  {
                    "message": "Bucket not found",
                    "code": 404
                  }
          500:
            body:
              application/json:
                type: ErrorResponse
                example: |
                  {
                    "message": "Failed to remove objects",
                    "code": 500
                  }

    /{objectKey}:
      uriParameters:
        bucketName:
          description: The name of the bucket.
          type: string
          required: true
        objectKey:
          description: >
            The key for the object (file) in the bucket, which may include slashes
            to simulate a directory structure. For example: `photos/2024/event1/image1.jpg`.
          type: string
          required: true

      get:
        description: Download or get metadata about an object in a bucket.
        queryParameters:
          metadataOnly?:
            description: If set to true, returns only object metadata (JSON).
            type: boolean
            default: false
        responses:
          200:
            description: Successful download or metadata retrieval.
            body:
              application/json:
                example: |
                  {
                    "key": "photos/2024/event1/image1.jpg",
                    "size": 2048,
                    "lastModified": "2024-01-10T10:00:00Z",
                    "type": "image/jpeg"
                  }
              application/octet-stream:
                description: The binary data (if metadataOnly is false and you want to download the file).
          404:
            body:
              application/json:
                type: ErrorResponse
                example: |
                  {
                    "message": "Object not found",
                    "code": 404
                  }

      put:
        description: Upload or update an object in the specified bucket.
        headers:
          Content-Type:
            description: The content type of the file being uploaded.
            example: "image/jpeg"
        body:
          application/octet-stream:
            description: The file data to be uploaded.
        responses:
          200:
            body:
              application/json:
                type: UploadResponse
                example: |
                  {
                    "key": "photos/2024/event1/image1.jpg",
                    "bucket": "photos"
                  }
          400:
            body:
              application/json:
                type: ErrorResponse
                example: |
                  {
                    "message": "Invalid file data or request parameters",
                    "code": 400
                  }
          404:
            body:
              application/json:
                type: ErrorResponse
                example: |
                  {
                    "message": "Bucket not found",
                    "code": 404
                  }

      delete:
        description: Delete an object from the specified bucket.
        responses:
          204:
            description: Object successfully deleted. No content returned.
          404:
            body:
              application/json:
                type: ErrorResponse
                example: |
                  {
                    "message": "Object not found",
                    "code": 404
                  }