alfresco-transform-core/docs/alfresco-transformer.yaml

swagger: '2.0'
info:
  description: |
    **Alfresco Transform Engines REST API**

    Transform Request & Response API to allow a source file to be transformed into a 
    target file, given a set of transform options. 
    
    The new JSON-based Transform Engines API is used by the Alfresco Transform Service (ATS).
    ATS provides an independently-scalable transform service, initially used by ACS 
    Content Repository, as part of the overall Alfresco Digital Business Platform (DBP).
    
    Note: Each kind of Transform Engine implements this Transform Engines API, including:
    
    * ImageMagick
    * LibreOffice
    * PDF Renderer
    * Tika
    
    In the future, this Transform Engines API may form the basis for adding custom Transform Engines.
    
  version: '1'
  title: Alfresco Transform Engines REST API
basePath: /alfresco/api/-default-/private/transformer/versions/1
tags:
  - name: Transform
    description: Transform Engine Request / Respone
paths:
  '/transform':
    post:
      x-alfresco-since: "2.0"
      tags:
        - Transform
      summary: Transform Engines API
      description: |
        **Note:** available with Alfresco Transform Engines 2.0 and newer versions.
        
        This endpoint supports both JSON and Multipart. The JSON API is used within the 
        Alfresco Transform Service (eg. ACS 6.1). The Multipart API remains for backwards 
        compatibility (eg. ACS 6.0).
        
        **Using JSON (application/json -> application/json)**
        
        The ACS Content Repository 6.1 (or higher) provides the option to offload 
        supported transformations to the Alfresco Transform Service.
         
        The JSON API is used within the Alfresco Transform Service. It relies on the 
        source and target files being stored and retrieved via the Alfresco Shared File 
        Store (see also [alfresco-sfs.yaml](https://github.com/Alfresco/alfresco-shared-file-store/blob/master/docs/api-definitions/alfresco-sfs.yaml)).       
        
        Here's a pseudo-example transform request:
        
        ```JSON
        {
          "schema": 1,
          "requestId": "0aead31c-e3ca-42c9-8e16-c1938ff64c3a",
          "clientData": "opaque-client-specific-data-123xyz",
          "sourceReference": "598387b8-d85d-4557-816e-50f44c969e04",
          "sourceSize": 32713,
          "sourceMediaType: "image/jpeg",
          "sourceExtension": "jpeg",
          "targetMediaType: "image/png",
          "targetExtension": "png",
          "transformRequestOptions": {
            "resizeWidth": "25",
            "resizePercentage": "true",
            "maintainAspectRatio": "true"
          }
        }
        ```
        
        Here's a pseudo-example response of a successful transform:
        
        ```JSON
        {
          "schema": 1,
          "status": 201
          "requestId": "0aead31c-e3ca-42c9-8e16-c1938ff64c3a",
          "clientData": "opaque-client-specific-data-123xyz",
          "sourceReference": "598387b8-d85d-4557-816e-50f44c969e04",
          "targetReference": "5bc81e48-e17a-4727-bd1c-3a279aa6b421"
        }
        ```
        
        Here's a pseudo-example response of a failed transform:
        
        ```JSON
        {
          "schema": 1,
          "status": 400,
          "errorDetails": "Lorem ipsum dolor sit amet, ..."
          "requestId": "0aead31c-e3ca-42c9-8e16-c1938ff64c3a",
          "clientData": "opaque-client-specific-data-123xyz",
          "sourceReference": "598387b8-d85d-4557-816e-50f44c969e04"
        }
        ```
        
        **Using Multipart (multipart/form-data -> application/octet-stream)**
        
        The Multipart API remains for backwards compatibility (eg. ACS 6.0). It requires 
        the source file to be uploaded via multipart/form-data (along with transformation 
        options). The target file is returned as a binary response (application/octet-steam).
        
      operationId: transformOperation
      parameters:
        - in: body
          name: transformRequest
          description: The Transform Request including source reference and transform options 
          required: true
          schema:
            $ref: '#/definitions/transformRequest'      
      consumes:
        - application/json
        - multipart/form-data
      produces:
        - application/json
        - application/octet-stream
      responses:
        '201':
          description: Successful response
          schema:
            $ref: '#/definitions/transformReply'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  '/transformer/options':
    get:
      tags:
      - Transform
      description: List transform options
      operationId: transformOptions
      produces:
      - application/json
      responses:
        200:
          description: Successful response
          schema:
            type: array
            xml:
              name: transformOptions
              wrapped: true
            items:
              $ref: '#/definitions/transformOption'
definitions:
  Error:
    type: object
    required:
      - error
    properties:
      error:
        type: object
        required:
          - statusCode
          - briefSummary
          - stackTrace
          - descriptionURL
        properties:
          errorKey:
            type: string
          statusCode:
            type: integer
            format: int32
          briefSummary:
            type: string
          stackTrace:
            type: string
          descriptionURL:
            type: string
          logId:
            type: string
  transformRequest:
    type: object
    properties:
      requestId:
        type: string
      sourceReference:
        type: string
      sourceMediaType:
        type: string
      sourceSize:
        type: integer
        format: int64
      sourceExtension:
        type: string
      targetMediaType:
        type: string
      targetExtension:
        type: string
      clientData:
        type: string
      schema:
        type: integer
      transformRequestOptions:
        type: object
        additionalProperties:
          type: string        
  transformReply:
    type: object
    properties:
      status:
        type: integer
      requestId:
        type: string
      sourceReference:
        type: string
      targetReference:
        type: string
      clientData:
        type: string
      schema:
        type: integer
      errorDetails:
        type: string
  transformOption:
    type: object
    required:
    - required
    - name
    properties:
      required:
        type: boolean
      name:
        type: string