REST API Reference
Relevant source files
The following files were used as context for generating this wiki page:
The Nextcloud CAD Viewer REST API provides the backend infrastructure necessary to serve CAD file metadata and content to the browser-based rendering engine. This API acts as a secure bridge between Nextcloud's filesystem and the @mlightcad/cad-viewer frontend library, ensuring that file access adheres to Nextcloud's internal permission systems.
The API is primarily focused on three tasks: retrieving file metadata (ID, name, size), streaming raw file content for rendering, and providing preview streams for CAD files. It is built using the Nextcloud App Framework's controller-based architecture.
Sources: lib/Controller/FileController.php, README.md:12-21
API Architecture and Security
The API is implemented within the FileController class. It utilizes Nextcloud's IRootFolder to interact with the filesystem and IUserSession to validate user identity. Security is enforced through attributes that bypass CSRF and Admin requirements for specific frontend interactions while manually checking user authorization and file readability.
The diagram above illustrates the validation logic applied to every API request handled by the FileController.
Sources: lib/Controller/FileController.php:49-145, src/App.vue:44-53
Authentication
The API supports standard Nextcloud authentication mechanisms, including Basic Auth and Bearer Auth (Token-based), as defined in the global API schema. Requests must typically include the OCS-APIRequest: true header to pass security filters.
Sources: openapi.json:11-23, openapi.json:59-71
Endpoint Reference
Get File Metadata
Retrieves technical metadata for a specific CAD file. This is often the first call made by the frontend to verify the file exists and is a supported format before attempting to load the heavy CAD data.
Endpoint: GET /apps/cad_viewer/api/file/{fileId}
| Parameter | Type | Required | Description |
|---|---|---|---|
fileId | integer | Yes | The internal Nextcloud file ID. |
Success Response (200 OK):
{
"id": 12345,
"name": "floorplan.dwg",
"size": 1048576,
"mimeType": "application/dwg",
"path": "path/to/file/floorplan.dwg"
}
Sources: lib/Controller/FileController.php:73-108, src/App.vue:53
Get File Content
Streams the raw binary content of the CAD file. This endpoint is used directly by the CAD viewer engine to download the DWG/DXF data into the browser's memory for WebGL rendering.
Endpoint: GET /apps/cad_viewer/api/file/{fileId}/content
| Parameter | Type | Required | Description |
|---|---|---|---|
fileId | integer | Yes | The internal Nextcloud file ID. |
Response Headers:
Content-Type: The specific CAD MIME type (e.g.,image/vnd.dwg).Content-Disposition:inline; filename="..."
Sources: lib/Controller/FileController.php:114-145, src/App.vue:53
Get File Preview
Provides a stream of the file content for preview purposes. In the current implementation, this serves the raw file stream similar to the content endpoint but is categorized for preview usage.
Endpoint: GET /apps/cad_viewer/api/file/{fileId}/preview
Sources: lib/Controller/FileController.php:151-182
Data Models and Constants
Supported MIME Types
The API strictly validates files against a whitelist of supported CAD formats. If a file's MIME type does not match this list, the API returns a 415 Unsupported Media Type error.
| MIME Type | Format |
|---|---|
application/acad | AutoCAD DWG |
application/dwg | AutoCAD DWG |
image/vnd.dwg | AutoCAD DWG |
image/vnd.dxf | AutoCAD DXF |
application/dxf | AutoCAD DXF |
| Sources: lib/Controller/FileController.php:33-44, README.md:92-97 |
OCS Meta Object
Standard metadata returned by OCS-compliant endpoints within the Nextcloud ecosystem.
| Field | Type | Description |
|---|---|---|
status | string | "ok" or "error" |
statuscode | integer | 100 for success, or error code |
message | string | Optional status message |
| Sources: openapi.json:26-48 |
Integration Flow
The frontend application (App.vue) orchestrates calls to these endpoints to initialize the viewer.
Error Handling
The API uses standard HTTP status codes to communicate failures:
| Status Code | Meaning | Cause |
|---|---|---|
| 401 | Unauthorized | User session is missing or expired. |
| 403 | Forbidden | User does not have read permissions for the file. |
| 404 | Not Found | The provided fileId does not exist. |
| 415 | Unsupported Media Type | The file is not a supported DWG or DXF format. |
| 500 | Internal Server Error | Unexpected filesystem or server failure. |
| Sources: lib/Controller/FileController.php:73-108, lib/Controller/FileController.php:114-145 |
This REST API ensures that the CAD Viewer remains a "zero-backend-requirement" rendering solution while still leveraging Nextcloud's robust security and file management capabilities.
Sources: appinfo/info.xml:8-15, README.md:5-10