QuantaCorp API

Authorization API

openapi: 3.0.0

info:
  title: QuantaCorp Authorization API
  description: This document contains the specs of the QuantaCorp Authorization API used at the initial phase of eTryOn iterative testing.
  version: 2.1.0

servers:
  - url: 'https://etryon.quantacorp.io/authorization'

externalDocs:
  description: Find out more about the QuantaCorp Authorization API and how to use it.
  url: 'https://docs.quantacorp.io'

security:
  - qc_basic: []

paths:
  /oauth2/token:
    post:
      summary: Create an oauth2 token.
      description: Request an oauth2 token by means of a username and password, or by means of a refresh token.
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              oneOf:
                - $ref: '#/components/schemas/UsernamePasswordForm'
                - $ref: '#/components/schemas/RefreshTokenForm'
                - $ref: '#/components/schemas/JwtForm'
        description: Form containg authentication data to request oauth2 token.
        required: true
      responses:
        '201':
          description: Created.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuth2Error'
        '500':
          description: Internal server error.

components:
  securitySchemes:
    qc_basic:
      type: http
      scheme: basic
  
  schemas:
    OAuth2Error:
      type: object
      properties:
        error:
          type: string
          enum:
            - invalid_client
            - invalid_request
            - unauthorized_client
            - invalid_token
            - invalid_grant
        error_description:
          type: string

    RefreshTokenForm:
      type: object
      properties:
        grant_type:
          type: string
          enum:
            - refresh_token
        refresh_token:
          type: string

    UsernamePasswordForm:
      type: object
      properties:
        grant_type:
          type: string
          enum:
            - password
        username:
          type: string
        password:
          type: string
          format: password

    JwtForm:
      type: object
      properties:
        grant_type:
          type: string
          enum:
            - jwt_token
        jwt_token:
          type: string

    TokenDTO:
      type: object
      properties:
        token_type:
          type: string
          enum:
            - Bearer
        access_token:
          type: string
        refresh_token:
          type: string
        expires_in:
          type: integer
          format: int32

Public API

openapi: 3.0.0

info:
  title: QuantaCorp Public API
  description: This document contains the specs of the QuantaCorp Public API used during the pilots.
  version: 2.1.0

servers:
  - url: 'https://etryon.quantacorp.io/public-api'

externalDocs:
  description: Find out more about the QuantaCorp Public API and how to use it.
  url: 'https://docs.quantacorp.io'

security:
  - qc_oauth2: []
  - etryon_bearer_auth: []

paths:
  /body:
    post:
      summary: Add a new body.
      description: Scans can only be added to specific project and body. In order to add a scan, a body has to be created first.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBodyDTO'
        description: Body object that needs to be created. Mind that the alias has to be unique within the company chain.
        required: true
      responses:
        '201':
          description: Created.
          headers:
            Location:
              schema:
                $ref: '#/components/schemas/Location'
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestExceptionDTO'
        '500':
          description: Internal server error.
  
  /async_scan/project/{projectId}/body/{bodyId}:
    post:
      summary: Register a new scan.
      description: Register a new scan for a given project and body.
      parameters:
        - in: path
          name: projectId
          schema:
            $ref: '#/components/schemas/NumericIdentifier'
          required: true
          description: Numeric ID of the project for which to add a scan
        - in: path
          name: bodyId
          schema:
            $ref: '#/components/schemas/NumericIdentifier'
          required: true
          description: Numeric ID of the body for which to add a scan
      responses:
        '202':
          description: Accepted. The scan is registered.
          headers:
            Location:
              schema:
                $ref: '#/components/schemas/Location'
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestExceptionDTO'
        '500':
          description: Internal server error.
  
  /async_scan/front/{scanId}:
    post:
      summary: Upload scan data for front pose.
      description: Upload scan data for front pose for scan with given ID.
      parameters:
        - in: path
          name: scanId
          schema:
            $ref: '#/components/schemas/NumericIdentifier'
          required: true
          description: Numeric ID of the scan for which to upload front pose data
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                frontMeta:
                  $ref: '#/components/schemas/PictureMetadataDTO'
                frontImage:
                  type: string
                  format: binary
            encoding:
              frontMeta:
                contentType: application/json
              frontImage:
                contentType: image/png
        description: All scan data for front pose.
        required: true
      responses:
        '200':
          description: OK. All scan data is uploaded.
          headers:
            Location:
              schema:
                $ref: '#/components/schemas/Location'
            X-Processing-Time:
              schema:
                $ref: '#/components/schemas/X-Processing-Time'
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestExceptionDTO'
        '500':
          description: Internal server error.
  
  /async_scan/side/{scanId}:
    post:
      summary: Upload scan data for side pose.
      description: Upload scan data for side pose for scan with given ID.
      parameters:
        - in: path
          name: scanId
          schema:
            $ref: '#/components/schemas/NumericIdentifier'
          required: true
          description: Numeric ID of the scan for which to upload side pose data
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                sideMeta:
                  $ref: '#/components/schemas/PictureMetadataDTO'
                sideImage:
                  type: string
                  format: binary
            encoding:
              sideMeta:
                contentType: application/json
              sideImage:
                contentType: image/png
        description: All scan data for side pose.
        required: true
      responses:
        '200':
          description: OK. All scan data is uploaded.
          headers:
            Location:
              schema:
                $ref: '#/components/schemas/Location'
            X-Processing-Time:
              schema:
                $ref: '#/components/schemas/X-Processing-Time'
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestExceptionDTO'
        '500':
          description: Internal server error.
  
  /async_scan/{scanId}/callbacks:
    post:
      summary: Add callbacks to a scan.
      description: Add callbacks for a scan with given ID. Handling callbacks is the last step in the processing of a scan. Make sure to send the callbacks-request timely.
      parameters:
        - in: path
          name: scanId
          schema:
            $ref: '#/components/schemas/NumericIdentifier'
          required: true
          description: Numeric ID of the scan for which to add callbacks
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/ScanCallbacksForm'
        description: Object containing all callbacks for a scan.
        required: true
      responses:
        '200':
          description: OK.
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestExceptionDTO'
        '500':
          description: Internal server error.

  /async_scan/process/{scanId}:
    post:
      summary: Request a scan to be processed.
      description: Create callbacks for a given scan. Handling callbacks is the last step in the processing of a scan. Make sure to send the callbacks-request timely.
      parameters:
        - in: path
          name: scanId
          schema:
            $ref: '#/components/schemas/NumericIdentifier'
          required: true
          description: Numeric ID of the scan for which to add callbacks
      responses:
        '202':
          description: Accepted. The scan started processing.
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestExceptionDTO'
        '500':
          description: Internal server error.

  /async_scan/status/{scanId}:
    get:
      summary: Request a scan's status.
      description: Fetch a status object describing the state of the scan's image resolution, segmentation, segmentation refinement, matching state and overal status.
      parameters:
        - in: path
          name: scanId
          schema:
            $ref: '#/components/schemas/NumericIdentifier'
          required: true
          description: Numeric ID of the scan for which to add callbacks
      responses:
        '200':
          description: OK. The response contains the scan status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncScanStatusDTO'
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestExceptionDTO'
        '500':
          description: Internal server error.

components:
  securitySchemes:
    qc_oauth2:
      type: oauth2
      flows:
        password:
          tokenUrl: 'https://etryon.quantacorp.io/authorization/oauth2/token'
          refreshUrl: 'https://etryon.quantacorp.io/authorization/oauth2/token'
          scopes: {}
    etryon_bearer_auth:
        type: 'http'
        scheme: 'bearer'
        bearerFormat: 'JWT'
  
  schemas:
    Location:
      type: string
      pattern: '^[a-z]+/[0-9]+$'
      description: Location header consists of the name of the resource followed by a forward slash and the numeric identifier (int64).
      example:
        body:
          value: body/1234
          summary: The location header for a body with ID 1234.
        scan:
          value: scan/5678
          summary: The location header for a scan with ID 5678.

    X-Processing-Time:
      type: integer
      format: int32
      description: The amount of time in seconds the client should wait before fetching scan result.

    NumericIdentifier:
      type: integer
      format: int64

    RestExceptionDTO:
      type: object
      properties:
        errorReason:
          type: string
        errorCode:
          type: integer
          format: int64
        externalMessage:
          type: string

    CreateBodyDTO:
      type: object
      properties:
        company_id:
          type: integer
          format: int64
        link_to_project:
          type: integer
          format: int64
        alias:
          type: string
        height:
          type: integer
          format: int32
        gender:
          type: string
          enum:
            - FEMALE
            - MALE
            - UNKNOWN
        weight:
          type: integer
          format: int32
      required:
        - company_id
        - link_to_project
        - alias
        - height
        - gender

    PictureMetadataDTO:
      type: object
      properties:
        gender:
          type: string
          enum:
            - F
            - M
            - U
        height:
          type: integer
          format: int32
        accelerometerX:
          type: number
          format: double
        accelerometerY:
          type: number
          format: double
        accelerometerZ:
          type: number
          format: double
        weight:
          type: integer
          format: int32
        fov_deg:
          type: number
          format: double
      required:
        - gender
        - height
        - accelerometerX
        - accelerometerY
        - accelerometerZ

    ScanCallbacksForm:
      type: object
      properties:
        ply_scape_callback:
          type: string
        ply_star_callback:
          type: string
        ply_morphed_callback:
          type: string
        etryon_meta_callback:
          type: string
        etryon_measurements_callback:
          type: string
        data_deletion_callback:
          type: string
          enum:
            - RGB_DELETION
            - COMPLETE_DELETION
        scan_final_status_callback:
          type: string
    
    AsyncScanStatusDTO:
      type: object
      properties:
        scan_id:
          type: integer
          format: int64
        front_image_resolution_type:
          type: string
          enum:
            - RESOLUTION_PENDING
            - LOW_RESOLUTION
            - HIGH_RESOLUTION
        side_image_resolution_type:
          type: string
          enum:
            - RESOLUTION_PENDING
            - LOW_RESOLUTION
            - HIGH_RESOLUTION
        front_image_segmentation_status_type:
          type: string
          enum:
            - PENDING_IMAGE_UPLOAD
            - PENDING_IMAGE_SEGMENTATION
            - PENDING_SEGMENTATION_REFINEMENT
            - SUCCESS
            - FAILURE_DURING_SEGMENTATION
            - FAILURE_DURING_REFINEMENT
            - REFINEMENT_SERVICE_NOT_AVAILABLE
            - RESOLUTION_TOO_LOW_FOR_SEGMENTATION_REFINEMENT
        side_image_segmentation_status_type:
          type: string
          enum:
            - PENDING_IMAGE_UPLOAD
            - PENDING_IMAGE_SEGMENTATION
            - PENDING_SEGMENTATION_REFINEMENT
            - SUCCESS
            - FAILURE_DURING_SEGMENTATION
            - FAILURE_DURING_REFINEMENT
            - REFINEMENT_SERVICE_NOT_AVAILABLE
            - RESOLUTION_TOO_LOW_FOR_SEGMENTATION_REFINEMENT
        front_image_segmentation_refinement_status_type:
          type: string
          enum:
            - PENDING_IMAGE_UPLOAD
            - PENDING_IMAGE_SEGMENTATION
            - PENDING_SEGMENTATION_REFINEMENT
            - SUCCESS
            - FAILURE_DURING_SEGMENTATION
            - FAILURE_DURING_REFINEMENT
            - REFINEMENT_SERVICE_NOT_AVAILABLE
            - RESOLUTION_TOO_LOW_FOR_SEGMENTATION_REFINEMENT
        side_image_segmentation_refinement_status_type:
          type: string
          enum:
            - PENDING_IMAGE_UPLOAD
            - PENDING_IMAGE_SEGMENTATION
            - PENDING_SEGMENTATION_REFINEMENT
            - SUCCESS
            - FAILURE_DURING_SEGMENTATION
            - FAILURE_DURING_REFINEMENT
            - REFINEMENT_SERVICE_NOT_AVAILABLE
            - RESOLUTION_TOO_LOW_FOR_SEGMENTATION_REFINEMENT
        scan_status_type:
          type: string
          enum:
            - PENDING_IMAGES
            - PENDING_SEGMENTATION
            - PENDING_SEGMENTATION_REFINEMENT
            - PENDING_MATCHING
            - FAILURE_IN_RESPONDER
            - FAILURE_IN_MATCHER
            - SUCCESS