openapi3.yml

openapi: 3.0.0
info:
  title: Svanill Vault
  description: |
    Svanill Vault, forward files produced by Svanill to an S3 compatible server.

    <!-- ReDoc-Inject: <security-definitions> -->
  contact: {}
  version: "1.0"
servers:
  - url: "https://{host}"
    variables:
      host:
        default: api.svanill.com
paths:
  /:
    get:
      tags:
        - Discovery
      summary: Discover endpoints
      operationId: GetStartingEndpoints
      parameters: []
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GetStartingEndpointsResponse"
              example:
                $ref: "#/components/schemas/GetStartingEndpointsResponse/x-examples/example"
      deprecated: false
      description: "Root endpoint, used as a starting point"
  /users/:
    post:
      tags:
        - User
      summary: Create user
      description: "Create a new user, that will be accessible by returning the correct answer to the provided challenge"
      operationId: CreateUser
      security:
        - BearerToken: []
      parameters: []
      requestBody:
        description: ""
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateUserRequest"
            x-examples:
              example:
                username: michael-walsh
                challenge: "<the challenge that the user will have to respond to>"
                answer: "<the answer that the user will have to give to pass the challenge>"
        required: true
      responses:
        "200":
          description: ""
          headers: {}
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreateUserResponse"
              x-examples:
                example:
                  status: 200
                  content:
                    challenge: "<the challenge that the user will have to respond to>"
                    token: "<auth token>"
                  links:
                    files_list:
                      href: "http://example.com/files/"
                      rel: file
                    request_upload_url:
                      href: "http://example.com/files/request-upload-url"
                      rel: file
      deprecated: false
    delete:
      tags:
        - User
      summary: Delete user
      description: Delete the user represented by the auth token
      operationId: DeleteUser
      security:
        - BearerToken: []
      responses:
        "200":
          description: ""
          headers: {}
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeleteUserResponse"
              x-examples:
                example:
                  status: 200
                  links:
                    create_user:
                      href: "http://example.com/users/"
                      rel: user
      deprecated: false
  /auth/request-challenge:
    get:
      tags:
        - Authentication
      summary: Ask for the challenge
      description: |
        Request a challenge so that we can prove we are who we claim to be
        (by sending the solution to [/auth/answer-challenge](#operation/AnswerUserChallenge))
      operationId: AskForTheChallenge
      parameters:
        - $ref: "#/components/parameters/usernameParam"
        - $ref: "#/components/parameters/contentTypeJsonHeader"
      responses:
        "200":
          description: ""
          headers: {}
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AskForTheChallengeResponse"
      deprecated: false
  /auth/answer-challenge:
    post:
      tags:
        - Authentication
      summary: "Answer user's challenge"
      description: |
        Answer the [challenge](#operation/AskForTheChallenge), to get back an auth token.
      operationId: AnswerUserChallenge
      parameters: []
      requestBody:
        description: ""
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AnswerUserChallengeRequest"
            x-examples:
              example:
                username: michael-walsh
                answer: "<the answer that was provided when creating the user>"
        required: true
      responses:
        "200":
          description: ""
          headers: {}
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AnswerUserChallengeResponse"
              x-examples:
                example:
                  status: 200
                  content:
                    token: "<auth token>"
                  links:
                    request_upload_url:
                      rel: file
                      href: "http://example.com/files/request-upload-url"
                    files_list:
                      rel: file
                      href: "http://example.com/files/"
      deprecated: false
  /files/:
    get:
      tags:
        - Files
      summary: "List the user's files"
      description: Retrieve a list of urls to the available files
      operationId: RetrieveListOfUserFiles
      security:
        - BearerToken: []
      parameters:
        - $ref: "#/components/parameters/contentTypeJsonHeader"
      responses:
        "200":
          description: ""
          headers: {}
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RetrieveListOfUserFilesResponse"
      deprecated: false
    delete:
      tags:
        - Files
      summary: Remove a file
      description: Permanently delete a file
      operationId: RemoveFile
      parameters:
        - $ref: "#/components/parameters/filenameParam"
      responses:
        "200":
          description: ""
          headers: {}
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RemoveFileResponse"
              x-examples:
                example:
                  status: 200
      deprecated: false
      security:
        - BearerToken: []
  /files/request-upload-url:
    post:
      tags:
        - Files
      summary: Request upload url
      description: Ask for a temporary url to upload a file (the url comes from an S3 compatible API server)
      operationId: RequestUploadUrl
      requestBody:
        description: ""
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RequestUploadUrlRequestBody"
        required: true
      responses:
        "200":
          description: ""
          headers: {}
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RequestUploadUrlResponse"
      deprecated: false
      security:
        - BearerToken: []
components:
  securitySchemes:
    BearerToken:
      type: http
      scheme: bearer
      description: |-
        `Authorization: Bearer <token>`

            $ curl -H "Authorization: Bearer 2AP9xR3tqpRHzFZxWcFAp2GtkFcXKU" -X GET "https://api.svanill.com/files/"
  schemas:
    GetStartingEndpointsResponse:
      title: GetStartingEndpointsResponse
      required:
        - status
        - links
      type: object
      properties:
        status:
          type: integer
          format: int32
        links:
          $ref: "#/components/schemas/GetStartingEndpointsResponseLinks"
      x-examples:
        example:
          status: 200
          links:
            create_user:
              href: "http://example.com/users/"
              rel: user
            request_auth_challenge:
              href: "http://example.com/auth/answer-challenge"
              rel: auth
    GetStartingEndpointsResponseLinks:
      title: GetStartingEndpointsResponseLinks
      required:
        - create_user
        - request_auth_challenge
      type: object
      properties:
        create_user:
          $ref: "#/components/schemas/HateoasCreateUser"
        request_auth_challenge:
          $ref: "#/components/schemas/HateoasRequestAuthChallenge"
      x-examples:
        example:
          create_user:
            href: "http://example.com/users/"
            rel: user
          request_auth_challenge:
            href: "http://example.com/auth/answer-challenge"
            rel: auth
    HateoasCreateUser:
      title: HateoasCreateUser
      required:
        - href
        - rel
      type: object
      properties:
        href:
          type: string
        rel:
          type: string
      x-examples:
        example:
          href: "http://example.com/users/"
          rel: user
    HateoasRequestAuthChallenge:
      title: HateoasRequestAuthChallenge
      required:
        - href
        - rel
      type: object
      properties:
        href:
          type: string
        rel:
          type: string
      x-examples:
        example:
          href: "http://example.com/auth/answer-challenge"
          rel: auth
    CreateUserRequest:
      title: CreateUserRequest
      required:
        - username
        - challenge
        - answer
      type: object
      properties:
        username:
          type: string
          description: "one or more ascii letters or numbers, underscores and hyphens. Must start with letters or numbers."
        challenge:
          type: string
          description: a public blob of text that will be presented to anyone that wants to log as this user
        answer:
          type: string
          description: a private blob of text that has to be provided during authorization in response to the challenge
      x-examples:
        example:
          username: michael-walsh
          challenge: "<the challenge that the user will have to respond to>"
          answer: "<the answer that the user will have to give to pass the challenge>"
    CreateUserResponse:
      title: CreateUserResponse
      required:
        - status
        - content
        - links
      type: object
      properties:
        status:
          type: integer
          format: int32
        content:
          $ref: "#/components/schemas/CreateUserResponseContent"
        links:
          $ref: "#/components/schemas/CreateUserResponseLinks"
      x-examples:
        example:
          status: 200
          content:
            challenge: "<the challenge that the user will have to respond to>"
            token: "<auth token>"
          links:
            files_list:
              href: "http://example.com/files/"
              rel: file
            request_upload_url:
              href: "http://example.com/files/request-upload-url"
              rel: file
    CreateUserResponseContent:
      title: CreateUserResponseContent
      required:
        - challenge
        - token
      type: object
      properties:
        challenge:
          type: string
        token:
          type: string
      x-examples:
        example:
          challenge: "<the challenge that the user will have to respond to>"
          token: "<auth token>"
    AnswerUserChallengeResponseLinks:
      title: AnswerUserChallengeResponseLinks
      required:
        - files_list
        - request_upload_url
      type: object
      properties:
        files_list:
          $ref: "#/components/schemas/HateoasFilesList"
        request_upload_url:
          $ref: "#/components/schemas/HateoasRequestUploadUrl"
      x-examples:
        example:
          files_list:
            href: "http://example.com/files/"
            rel: file
          request_upload_url:
            href: "http://example.com/files/request-upload-url"
            rel: file
    HateoasFilesList:
      title: HateoasFilesList
      required:
        - href
        - rel
      type: object
      properties:
        href:
          type: string
        rel:
          type: string
      x-examples:
        example:
          href: "http://example.com/files/"
          rel: file
    CreateUserResponseLinks:
      title: CreateUserResponseLinks
      required:
        - files_list
        - request_upload_url
      type: object
      properties:
        files_list:
          $ref: "#/components/schemas/HateoasFilesList"
        request_upload_url:
          $ref: "#/components/schemas/HateoasRequestUploadUrl"
      x-examples:
        example:
          files_list:
            href: "http://example.com/files/"
            rel: file
          request_upload_url:
            href: "http://example.com/files/request-upload-url"
            rel: file
    HateoasRequestUploadUrl:
      title: HateoasRequestUploadUrl
      required:
        - href
        - rel
      type: object
      properties:
        href:
          type: string
        rel:
          type: string
      x-examples:
        example:
          href: "http://example.com/files/request-upload-url"
          rel: file
    HateoasFileUploadUrl:
      title: HateoasFileUploadUrl
      required:
        - href
        - rel
        - form_data
      type: object
      properties:
        href:
          type: string
        rel:
          type: string
        form_data:
          type: object
          additionalProperties:
            type: string
      x-examples:
        example:
          href: "http://example.com/files/request-upload-url"
          rel: file
          form_data: "<form data to use to do the upload request>"
    HateoasFileRetrieveUrl:
      title: HateoasFileRetrieveUrl
      required:
        - href
        - rel
      type: object
      properties:
        href:
          type: string
        rel:
          type: string
      x-examples:
        example:
          href: "http://example.com/files/request-upload-url"
          rel: file
    DeleteUserResponse:
      title: DeleteUserResponse
      required:
        - status
        - links
      type: object
      properties:
        status:
          type: integer
          format: int32
        links:
          $ref: "#/components/schemas/DeleteUserResponseLinks"
      x-examples:
        example:
          status: 200
          links:
            create_user:
              href: "http://example.com/users/"
              rel: user
    DeleteUserResponseLinks:
      title: DeleteUserResponseLinks
      required:
        - create_user
      type: object
      properties:
        create_user:
          $ref: "#/components/schemas/HateoasCreateUser"
      x-examples:
        example:
          create_user:
            href: "http://example.com/users/"
            rel: user
    AskForTheChallengeResponse:
      title: AskForTheChallengeResponse
      required:
        - status
        - content
        - links
      type: object
      properties:
        status:
          type: integer
          format: int32
        content:
          $ref: "#/components/schemas/AskForTheChallengeResponseContent"
        links:
          $ref: "#/components/schemas/AskForTheChallengeResponseLinks"
      x-examples:
        example:
          status: 200
          content:
            challenge: "<the challenge that the user will have to respond to>"
          links:
            answer_auth_challenge:
              rel: auth
              href: "http://example.com/auth/answer-challenge"
            create_user:
              rel: user
              href: "http://example.com/users/"
    AskForTheChallengeResponseContent:
      title: AskForTheChallengeResponseContent
      required:
        - challenge
      type: object
      properties:
        challenge:
          type: string
      x-examples:
        example:
          challenge: "<the challenge that the user will have to respond to>"
    AskForTheChallengeResponseLinks:
      title: AskForTheChallengeResponseLinks
      required:
        - answer_auth_challenge
        - create_user
      type: object
      properties:
        answer_auth_challenge:
          $ref: "#/components/schemas/HateoasAnswerAuthChallenge"
        create_user:
          $ref: "#/components/schemas/HateoasCreateUser"
      x-examples:
        example:
          answer_auth_challenge:
            rel: auth
            href: "http://example.com/auth/answer-challenge"
          create_user:
            rel: user
            href: "http://example.com/users/"
    HateoasAnswerAuthChallenge:
      title: HateoasAnswerAuthChallenge
      required:
        - rel
        - href
      type: object
      properties:
        rel:
          type: string
        href:
          type: string
      x-examples:
        example:
          rel: auth
          href: "http://example.com/auth/answer-challenge"
    AnswerUserChallengeRequest:
      title: AnswerUserChallengeRequest
      required:
        - username
        - answer
      type: object
      properties:
        username:
          type: string
          description: the username of the user you claim to be
        answer:
          type: string
          description: the answer to the challenge
      x-examples:
        example:
          username: michael-walsh
          answer: "<the answer that was provided when creating the user>"
    AnswerUserChallengeResponse:
      title: AnswerUserChallengeResponse
      required:
        - status
        - content
        - links
      type: object
      properties:
        status:
          type: integer
          format: int32
        content:
          $ref: "#/components/schemas/AnswerUserChallengeResponseContent"
        links:
          $ref: "#/components/schemas/AnswerUserChallengeResponseLinks"
      x-examples:
        example:
          status: 200
          content:
            token: "<auth token>"
          links:
            request_upload_url:
              rel: file
              href: "http://example.com/files/request-upload-url"
            files_list:
              rel: file
              href: "http://example.com/files/"
    RequestUploadUrlResponse:
      title: RequestUploadUrlResponse
      required:
        - status
        - links
      type: object
      properties:
        status:
          type: integer
          format: int32
        links:
          $ref: "#/components/schemas/RequestUploadUrlResponseLinks"
      x-examples:
        example:
          status: 200
          links:
            upload_url:
              rel: file
              href: "http://<bucket.s3like>/path/to/file-with-extra-query-params"
              form_data: "<form data to use to do the upload request>"
            retrieve_url:
              rel: file
              href: "http://<bucket.s3like>/path/to/file"
    RequestUploadUrlResponseLinks:
      title: RequestUploadUrlResponseLinks
      required:
        - upload_url
        - retrieve_url
      type: object
      properties:
        upload_url:
          $ref: "#/components/schemas/HateoasFileUploadUrl"
        retrieve_url:
          $ref: "#/components/schemas/HateoasFileRetrieveUrl"
      x-examples:
        example:
          upload_url:
            rel: file
            href: "http://<bucket.s3like>/path/to/file-with-extra-query-params"
            form_data: "<form data to use to do the upload request>"
          retrieve_url:
            rel: file
            href: "http://<bucket.s3like>/path/to/file"
    AnswerUserChallengeResponseContent:
      title: AnswerUserChallengeResponseContent
      required:
        - token
      type: object
      properties:
        token:
          type: string
      x-examples:
        example:
          token: "<auth token>"
    RetrieveListOfUserFilesResponse:
      title: RetrieveListOfUserFilesResponse
      required:
        - status
        - content
      type: object
      properties:
        status:
          type: integer
          format: int32
        content:
          type: array
          items:
            $ref: "#/components/schemas/RetrieveListOfUserFilesResponseContentItem"
          description: ""
      x-examples:
        example:
          status: 200
          content:
            - links:
                read:
                  rel: file
                  href: "http://<s3-like-server>/bucket-test/users/foo/file1"
                delete:
                  rel: file
                  href: "http://example.com/files/"
              content:
                checksum: 9297ab3fbd56b42f6566284119238125
                filename: file1
                size: 9
                url: "http://<s3-like-server>/bucket-test/users/foo/file1"
            - links:
                read:
                  rel: file
                  href: "http://<s3-like-server>/bucket-test/users/foo/file2"
                delete:
                  rel: file
                  href: "http://example.com/files/"
              content:
                checksum: 6685cd62b95f2c58818cb20e7292168b
                filename: file2
                size: 9
                url: "http://<s3-like-server>/bucket-test/users/foo/file2"
    RetrieveListOfUserFilesResponseContentItem:
      title: RetrieveListOfUserFilesResponseContentItem
      required:
        - links
        - content
      type: object
      properties:
        links:
          $ref: "#/components/schemas/RetrieveListOfUserFilesResponseContentItemLinks"
        content:
          $ref: "#/components/schemas/RetrieveListOfUserFilesResponseContentItemContent"
      x-examples:
        example:
          links:
            read:
              rel: file
              href: "http://<s3-like-server>/bucket-test/users/foo/file1"
            delete:
              rel: file
              href: "http://example.com/files/"
          content:
            checksum: 9297ab3fbd56b42f6566284119238125
            filename: file1
            size: 9
            url: "http://<s3-like-server>/bucket-test/users/foo/file1"
    RetrieveListOfUserFilesResponseContentItemLinks:
      title: RetrieveListOfUserFilesResponseContentItemLinks
      required:
        - read
        - delete
      type: object
      properties:
        read:
          $ref: "#/components/schemas/HateoasFileRead"
        delete:
          $ref: "#/components/schemas/HateoasFileDelete"
      x-examples:
        example:
          read:
            rel: file
            href: "http://<s3-like-server>/bucket-test/users/foo/file1"
          delete:
            rel: file
            href: "http://example.com/files/"
    HateoasFileRead:
      title: HateoasFileRead
      required:
        - rel
        - href
      type: object
      properties:
        rel:
          type: string
        href:
          type: string
      x-examples:
        example:
          rel: file
          href: "http://<s3-like-server>/bucket-test/users/foo/file1"
    HateoasFileDelete:
      title: HateoasFileDelete
      required:
        - rel
        - href
      type: object
      properties:
        rel:
          type: string
        href:
          type: string
      x-examples:
        example:
          rel: file
          href: "http://example.com/files/"
    RetrieveListOfUserFilesResponseContentItemContent:
      title: RetrieveListOfUserFilesResponseContentItemContent
      required:
        - checksum
        - filename
        - size
        - url
      type: object
      properties:
        checksum:
          type: string
        filename:
          type: string
        size:
          type: integer
          format: int32
        url:
          type: string
      x-examples:
        example:
          checksum: 9297ab3fbd56b42f6566284119238125
          filename: file1
          size: 9
          url: "http://<s3-like-server>/bucket-test/users/foo/file1"
    RemoveFileResponse:
      title: RemoveFileResponse
      required:
        - status
      type: object
      properties:
        status:
          type: integer
          format: int32
      x-examples:
        example:
          status: 200
    RequestUploadUrlRequestBody:
      title: RequestUploadUrlRequestBody
      required:
        - filename
      type: object
      properties:
        filename:
          type: string
          description: the name of the file to upload
      x-examples:
        example:
          filename: "<the name of the file to upload>"
  parameters:
    usernameParam:
      name: username
      in: query
      description: "the username we're requesting the challenge for"
      required: true
      style: form
      explode: true
      schema:
        type: string
        example: michael-walsh
    contentTypeJsonHeader:
      name: Content-Type
      in: header
      description: ""
      required: true
      style: simple
      schema:
        type: string
        enum:
          - application/json
    filenameParam:
      name: filename
      in: query
      description: the name of the file to delete
      required: true
      style: form
      explode: true
      schema:
        type: string
tags:
  - name: Discovery
    description: "Don't know where to go? Just ask `/`"
  - name: Authentication
    description: |
      To create a new account, the user must provide some content to use as challenge and an answer to that challenge.

      To authenticate, the user requests the challenge and provides the answer.

      The challenge is supposed to contain the answer, encrypted through a cryptographic algorithm that does not suffer from known-plaintext attack.

      <!-- ReDoc-Inject: <security-definitions> -->
  - name: User
    description: "Users' management"
  - name: Files
    description: "Upload, delete or retrieve files"