Aspose.HTML Cloud 20.11 Release Notes
Aspose.HTML Cloud for .NET
We are pleased to announce that the Aspose.HTML Cloud API version has been upgraded to v4.0, due to significant extension of the cloud API. The following features has been exposed as API version 4.0 (for details, see v.20.11 Api Changes ):
- a group of conversion API methods has been implemented to complete the following goals:
- a big variety of v3.0 conversion methods has been replaced with unified interface for all supported conversion cases;
- conversion operation may be long-time, so it has been implemented as asynchronous, following CQRS pattern. So the conversion API is reduced to 3 entry points: 1) command that starts a long-time processing; 2) query that checks the previously started operation state; 3) query that cancels the running operation. -alternative storage access API has been implemented; it has some advantages compared with existing Storage API v3.0
Old style API of version 3.0 is still available.
API changes
Common path format conventions
The source and result document paths must match the following conventions:
| Protocol | Template | Description |
|---|---|---|
| http, https | {protocol}://hostname/[path]/[pagename.html] | Only source documents. These paths are valid Web URLs that can represent both static HTML pages or dynamic HTML content pages generated by CGI, ASP, JSP, PHP and so on. |
| storage | storage://storageName/[Folder1]/[Folder2]/…/FileName.ext - storage file storage://storageName/[Folder1]/[Folder2]/…/[FolderN] - storage folder | Source and result documents. This type of paths represents files or folders in the Aspose cloud storage associated with the application user. The path specifies the storageName (can be empty for user application’s default storage) and file/folder full path in the storage. The document lifetime is controlled by the storage associated user. |
| app | app:///[Folder1]/[Folder2]/…/FileName.ext | Source and result documents. In a common case, these are results of an operation where outputPath wasn’t explicitly specified. This type of paths represents files in the internal temporary storage; they are available for download during a limited time period. Generally are used internally by client SDKs, but also can be used by other applications that use Aspose.HTML Cloud API v4.0 directly |
| (omitted) | /[Folder1]/[Folder2]/…/FileName.ext | By default, Conversion API treats these paths as path in the default cloud storage. Storage API uses only such paths, additional storage parameter may be specified or not. |
New feature
Conversion API
- POST: start a long-time conversion operation. If succeeded, returns a response with operation ID.
/convert?inputPath={inputPath}&outputFormat={outputFormat}&outputPath={outputPath}
Parameters:
| Name | Description | Passed in | Required |
|---|---|---|---|
| inputPath | Location of source document to be converted. | Query | + |
| outputFormat | Format the source document will be converted to. Supported values: PDF, XPS, MHTML, MD, JPG, PNG, BMP, GIF, TIFF | Query | + |
| outputPath | Location where the conversion result will be saved. By default, the result document will be saved to internal temporary storage (see app:// paths above) | Query | - |
| width | Result document page or image width in in points (1/96 inch) | Body | - |
| height | Result document page or image height in in points (1/96 inch) | Body | - |
| leftmargin | Result document page or image left margin in points (1/96 inch) | Body | - |
| rightmargin | Result document page or image right margin in points (1/96 inch) | Body | - |
| topmargin | Result document page or image top margin in points (1/96 inch) | Body | - |
| bottommargin | Result document page or image bottom margin in points (1/96 inch) | Body | - |
| resolution | Resolution of resulting image. Default is 96 dpi. Applicable only to image formats. | Body | - |
| jpegquality | JPEG image quality, valid values from 0 to 100. Default is 96. Applicable only to JPEG image format. | Body | - |
| usegit | Use GIT flavor of Markdown (false by default). Applicable only to MD format. | Body | - |
- GET: check the previously started operation state by its ID. Returns the state object; if state code is “completed”, the response object will contain a list of converted file paths. The conversion results are stored in the cloud storage and will be available for download using cloud paths from the response.
/convert/{id}
Parameters:
| Name | Description | Passed in | Required |
|---|---|---|---|
| id | ID of conversion task previously started. | Path | + |
- DELETE: cancel the previously started operation by its ID
/convert/{id}
Parameters:
| Name | Description | Passed in | Required |
|---|---|---|---|
| id | ID of conversion task previously started. | Path | + |
Storage API
The main difference of Storage API v4.0 from v3.0 is that storage paths are specified in the query parameters, not in the API command URL path; it allows to avoid issues that may occur when file/folder paths contain spaces or national characters.
Storage
- GET: check if a specified storage exists and is associated with application user:
/storage/exist/storage?storageName={storageName}
Parameters:
| Name | Description | Passed in | Required |
|---|---|---|---|
| storageName | Storage name. | Query | + |
- GET: check if specified file or folder exists in the specified or default storage.
/storage/exist?path={path}&storageName={storageName}&versionId={versionId}
Parameters:
| Name | Description | Passed in | Required |
|---|---|---|---|
| path | Object (file or folder) path in the storage. | Query | + |
| storageName | Storage name, or default storage if not specified. | Query | - |
| versionId | Version ID of the specified file, or last version by default. Ignored for folders | Query | - |
- GET: return a total and used disc space in bytes of the specified storage.
/storage/disc?storageName={storageName}
Parameters:
| Name | Description | Passed in | Required |
|---|---|---|---|
| storageName | Storage name | Query | + |
- GET: return a list of versions of specified file, if versioning is supported by the specified or default storage.
/storage/versions?path={path}&storageName={storageName}
Parameters:
| Name | Description | Passed in | Required |
|---|---|---|---|
| path | File path in the storage. | Query | + |
| storageName | Storage name, or default storage if not specified. | Query | - |
Folder
- GET: return a list of files and folders in the specified folder (or in the root folder by default) of the storage.
/folder?path={path}&storageName={storageName}
Parameters:
| Name | Description | Passed in | Required |
|---|---|---|---|
| path | Folder path in the storage. | Query | + |
| storageName | Storage name, or default storage if not specified. | Query | - |
- POST: create a folder
/folder?path={path}&storageName={storageName}
Parameters:
| Name | Description | Passed in | Required |
|---|---|---|---|
| path | Folder path to be created. | Query | + |
| storageName | Storage name, or default storage if not specified. | Query | - |
- PUT: copy the specified folder with files and subfolders to the new path.
/folder/copy?srcpath={srcPath}&destpath={destPath}&srcstoragename={srcStorageName}&srcstoragename={destStorageName}
Parameters:
| Name | Description | Passed in | Required |
|---|---|---|---|
| srcPath | Source folder path to be copied. | Query | + |
| destPath | Destination folder path | Query | + |
| srcStorageName | Source folder storage name, or default storage if not specified. | Query | - |
| destStorageName | Destination folder storage name, or default storage if not specified. | Query | - |
- PUT: move the specified folder with files and subfolders to the new path.
/folder/move?srcpath={srcPath}&destpath={destPath}&srcstoragename={srcStorageName}&srcstoragename={destStorageName}
Parameters:
| Name | Description | Passed in | Required |
|---|---|---|---|
| srcPath | Source folder path to be moved. | Query | + |
| destPath | Destination folder path | Query | + |
| srcStorageName | Source folder storage name, or default storage if not specified. | Query | - |
| destStorageName | Destination folder storage name, or default storage if not specified. | Query | - |
- DELETE: delete the specified folder.
/folder?path={path}&storageName={storageName}
Parameters:
| Name | Description | Passed in | Required |
|---|---|---|---|
| path | Folder path to be deleted. | Query | + |
| storageName | Storage name, or default storage if not specified. | Query | - |
File
- GET: download a file. Response object contains the raw data of the file.
/file?path={path}&storageName={storageName}&versionId={versionId}
Parameters:
| Name | Description | Passed in | Required |
|---|---|---|---|
| path | File path to be downloaded. | Query | + |
| storageName | Storage name, or default storage if not specified. | Query | - |
| versionId | File version ID, or the last version by default | Query | - |
- POST: upload a file. If file exists, new version of the file will be added on the same location.
/file?path={path}&storageName={storageName}
Parameters:
| Name | Description | Passed in | Required |
|---|---|---|---|
| path | File uploading path. | Query | + |
| storageName | Storage name, or default storage if not specified. | Query | - |
| - | File content to upload; it must be passed in the HTTP request body. Requires an HTTP header Content-Type=application/multipart-data | Body | + |
- PUT: copy the specified file to another path (if versionId is specified, this version will be copied)
/file/copy?srcpath={srcPath}&destpath={destPath}&srcstoragename={srcStorageName}&srcstoragename={destStorageName}&versionId={versionId}
Parameters:
| Name | Description | Passed in | Required |
|---|---|---|---|
| srcPath | Source file path to be copied. | Query | + |
| destPath | Destination file/folder path | Query | + |
| srcStorageName | Source file storage name, or default storage if not specified. | Query | - |
| destStorageName | Destination file storage name, or default storage if not specified. | Query | - |
| versionId | File version ID, or the last version by default | Query | - |
- PUT: move the specified file to another path (if versionId is specified, this version will be copied to new location and deleted)
/file/move?srcpath={srcPath}&destpath={destPath}&srcstoragename={srcStorageName}&srcstoragename={destStorageName}&versionId={versionId}
Parameters:
| Name | Description | Passed in | Required |
|---|---|---|---|
| srcPath | Source file path to be moved. | Query | + |
| destPath | Destination file/folder path | Query | + |
| srcStorageName | Source file storage name, or default storage if not specified. | Query | - |
| destStorageName | Destination file storage name, or default storage if not specified. | Query | - |
| versionId | File version ID, or the last version by default | Query | - |
- DELETE: delete a file. Only last version will be deleted by default; if versionId is specified, only this version will be deleted.
/file?path={path}&storageName={storageName}&versionId={versionId}
Parameters:
| Name | Description | Passed in | Required |
|---|---|---|---|
| path | File path to be deleted. | Query | + |
| storageName | Storage name, or default storage if not specified. | Query | - |
| versionId | File version ID, or the last version by default | Query | - |