From dc12a2743a36fe7ed082138d327082886040bb57 Mon Sep 17 00:00:00 2001 From: janv Date: Mon, 3 Sep 2018 15:39:11 +0100 Subject: [PATCH] ATS-17: Add private OpenAPI spec for Alfresco Transform Engines API - first draft for /transform REST API (including basic T-Request / T-Reply model definitions) --- docs/alfresco-transformer.yaml | 191 +++++++++++++++++++++++++++++++++ 1 file changed, 191 insertions(+) create mode 100644 docs/alfresco-transformer.yaml diff --git a/docs/alfresco-transformer.yaml b/docs/alfresco-transformer.yaml new file mode 100644 index 00000000..f73c9b5d --- /dev/null +++ b/docs/alfresco-transformer.yaml @@ -0,0 +1,191 @@ +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/form-data. + + **Using JSON (application/json -> application/json)** + + The JSON API relies on the source and target files to be stored and retrieved via + the Shared File Store. This is used within the Alfresco Transform Service. + The ACS Content Repository 6.1 (or higher) provides the option to offload + supported transformations to the Alfresco Transform Service. + + 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 an 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 an pseudo-example response of a successful transform: + + ```JSON + { + "schema": 1, + "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' +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