From dc12a2743a36fe7ed082138d327082886040bb57 Mon Sep 17 00:00:00 2001 From: janv Date: Mon, 3 Sep 2018 15:39:11 +0100 Subject: [PATCH 1/2] 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 From a93989e0453232edc07ee0b401a4a122e0782ad9 Mon Sep 17 00:00:00 2001 From: janv Date: Tue, 11 Sep 2018 11:31:46 +0100 Subject: [PATCH 2/2] ATS-17: Add private OpenAPI spec for Alfresco Transform Engines API - updates based on initial review comments, including -- fix typo (s/successful/failed) -- add example error status code -- add link to Alfresco SFS API spec - also slight re-wording of /transform description --- docs/alfresco-transformer.yaml | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/docs/alfresco-transformer.yaml b/docs/alfresco-transformer.yaml index f73c9b5d..224c576e 100644 --- a/docs/alfresco-transformer.yaml +++ b/docs/alfresco-transformer.yaml @@ -35,14 +35,18 @@ paths: description: | **Note:** available with Alfresco Transform Engines 2.0 and newer versions. - This endpoint supports both JSON and multipart/form-data. + 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 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. + + 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: @@ -65,7 +69,7 @@ paths: } ``` - Here's an pseudo-example response of a successful transform: + Here's a pseudo-example response of a successful transform: ```JSON { @@ -78,11 +82,12 @@ paths: } ``` - Here's an pseudo-example response of a successful transform: + 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",