swagger: '2.0' info: title: "Draftable Compare API" version: "1.0.0.0" host: api.draftable.com schemes: https basePath: /v1 paths: /comparisons: post: summary: Create a comparison description: | Create a comparison by sending 2 files (either by a URL or direct upload), as well as some other metadata used to display the comparison. For each of the left and right files, either a source_url or a file must be provided and not both. If you pass in an identifier, you will be able to preload the comparison page. If not, an identifier will be generated and returned in the response. operationId: createComparison consumes: - multipart/form-data parameters: - name: identifier in: formData description: Unique identifier for the comparison. type: string required: false allowEmptyValue: true - name: left.file in: formData description: The left file, as bytes. type: file required: false - name: left.source_url in: formData description: Source URL for the left file. type: string format: URL required: false - name: left.display_name in: formData description: Display name for the left file. type: string required: false allowEmptyValue: true - name: left.file_type in: formData description: File type of left file. type: string enum: - pdf - txt - rtf - doc - docx - docm - ppt - pptx - pptm required: true - name: right.file in: formData description: The right file, as bytes. type: file required: false - name: right.source_url in: formData description: Source URL for the right file. type: string format: URL required: false - name: right.display_name in: formData description: Display name for the right file. type: string required: false allowEmptyValue: true - name: right.file_type in: formData description: File type of right file. type: string enum: - pdf - txt - rtf - doc - docx - docm - ppt - pptx - pptm required: true - name: public in: formData description: Whether the comparison can be viewed without authentication. Defaults to false. type: boolean required: false default: false - name: expiry_time in: formData description: When the comparison will be automatically deleted. Defaults to no expiry. type: string format: date-time required: false tags: - Comparison responses: 201: description: Successfully created a comparison. schema: $ref: '#/definitions/Comparison' 400: description: The request was malformed. get: summary: List all comparisons description: Lists all comparisons, limited to 300 per page. operationId: listComparisons parameters: - name: limit required: false in: query description: The maximum number of comparisons to be returned. Defaults to no limit. type: integer - name: offset required: false in: query description: The number of comparisons to skip. type: integer tags: - Comparison responses: 200: description: Returns a list of objects giving information about each comparison under "results". schema: type: object required: - count - results properties: count: type: integer description: The total number of comparisons minimum: 0 # This default is so that the example response makes sense. default: 1 limit: type: integer description: The maximum number of comparisons returned; defaults to no limit offset: type: integer description: The number of comparisons to skip results: type: array description: An array of `Comparison` objects items: $ref: '#/definitions/Comparison' /comparisons/{identifier}: get: summary: Get a comparison description: Gets the comparison with the given identifier, including the current status and other initial request information. operationId: getComparison parameters: - required: true in: path description: The comparison's identifier. type: string name: identifier tags: - Comparison responses: 200: description: Comparison found schema: $ref: '#/definitions/Comparison' 404: description: Comparison not found delete: summary: Delete a comparison description: Deletes the comparison with the given identifier. operationId: deleteComparison parameters: - required: true in: path description: The comparison's identifier. type: string name: identifier tags: - Comparison responses: 204: description: Successfully deleted the comparison 404: description: Comparison not found /exports: post: summary: Export comparison as PDF description: | Export the comparison to PDF by sending the comparison identifier along with the requested export kind. Four export kinds are supported. - single_page: Displays the right side document only with highlights and deletion markers showing the diff - combined: Displays both right and left sides - left: Displays left side only - right: Displays right side only After creating the export, you must poll using the export identifier to obtain the URL of the exported document. operationId: createExport parameters: - name: comparison required: true in: formData description: The identifier of the comparison to be exported. type: string - name: kind required: true in: formData description: Export kind. type: string enum: - single_page - combined - left - right - name: include_cover_page required: false in: formData description: Decides if cover page is included for combined export. Defaults to true. type: boolean tags: - Export responses: 201: description: Successfully created an export. schema: $ref: '#/definitions/Export' 400: description: The request was malformed. /exports/{identifier}: get: summary: Get an export description: Gets the export with the given identifier, including the current status and other initial request information. operationId: getExport parameters: - name: identifier required: true in: path description: The export's identifier. type: string tags: - Export responses: 200: description: Export found schema: $ref: '#/definitions/Export' 404: description: Export not found definitions: Comparison: type: object required: - identifier - left - right - creation_time - ready - public properties: identifier: type: string description: Unique identifier for the comparison left: $ref: '#/definitions/File' description: Properties of the left file right: $ref: '#/definitions/File' description: Properties of the right file creation_time: type: string format: date-time description: When the comparison was submitted expiry_time: type: string format: date-time description: When the comparison will be automatically deleted public: type: boolean description: Whether the comparison can be viewed without authentication ready: type: boolean description: Whether the comparison is ready ready_time: type: string format: date-time description: If ready, when the comparison became ready failed: type: boolean description: If ready, whether the comparison failed error_message: type: string description: If failed, a description of the error example: identifier: "example-identifier" left: source_url: "https://www.testurl.com/old-example.docx" display_name: "old-example.docx" file_type: "docx" right: source_url: "https://www.testurl.com/newer-example.docx" display_name: "newer-example.docx" file_type: "docx" creation_time: "2017-02-08T14:31:32.630Z" expiry_time: "2017-02-15T14:31:32.630Z" public: false ready: false File: type: object properties: file: type: string description: If a file wasFile URL of file (if it was given) example: "" source_url: type: string description: Source URL of file (if it was given) example: https://www.testurl.com/example.docx display_name: type: string description: Display name of file. example: example.docx file_type: type: string enum: - pdf - ppt - pptx - pptm - doc - docx - docm - rtf - txt description: File type of file example: docx Export: type: object required: - identifier - comparison - kind - ready - failed properties: identifier: type: string description: Unique identifier for the export comparison: type: string description: Unique identifier for the comparison kind: type: string enum: - single_page - combined - left - right description: The kind of export url: type: string description: The signed URL where the export can be downloaded ready: type: boolean description: Whether the export is ready failed: type: boolean description: If ready, whether the export failed error_message: type: string description: If failed, a description of the error example: identifier: "example-identifier" comparison: "example-comparison-identifier" url: "https://draftable-diff-api-dev.s3.amazonaws.com/example" kind: "single_page" ready: true failed: false