services/ocdav/ocdav-openapi.yaml
Rama master · réplica de lectura del repositorio original.
openapi: 3.1.0
info:
title: oCIS WebDAV API
description: |
The oCIS WebDAV API provides Web Distributed Authoring and Versioning (WebDAV) functionality for file and folder
management, metadata operations, and resource locking. WebDAV extends HTTP/1.1 with additional methods, headers,
and content-types for comprehensive resource management.
This API is one of the central interfaces that ownCloud clients use for handling file resources, metadata, and locks.
It supports the full WebDAV specification (RFC 4918) with ownCloud-specific extensions.
**Key Features:**
- File and folder operations (create, read, update, delete)
- Property management and metadata operations
- Resource locking and collision avoidance
- Directory listings and resource discovery
- Resumable uploads via TUS protocol integration
- ownCloud-specific properties and extensions
**WebDAV Methods:**
This API uses standard HTTP methods where possible, and documents WebDAV-specific methods
using POST with method override headers for compatibility with OpenAPI tooling.
version: 1.0.0
contact:
name: ownCloud
url: https://github.com/owncloud/ocis
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://your-ocis-instance.com
description: oCIS instance
security:
- BearerAuth: []
- BasicAuth: []
paths:
/dav/spaces/{resourceId}:
parameters:
- $ref: '#/components/parameters/ResourceId'
get:
summary: Download Resource
description: |
Downloads a file or retrieves information about a folder. This is the standard HTTP GET method
applied to WebDAV resources. For files, it returns the file content with appropriate headers.
For folders, it may return an HTML representation or redirect to a PROPFIND operation.
operationId: downloadResource
tags:
- Resource Operations
parameters:
- $ref: '#/components/parameters/PathParam'
- name: Range
in: header
description: Request specific byte ranges of the file
schema:
type: string
example: "bytes=0-1023"
responses:
'200':
description: Resource content retrieved successfully
headers:
Content-Type:
schema:
type: string
description: MIME type of the resource
Content-Length:
schema:
type: integer
description: Size of the resource in bytes
ETag:
schema:
type: string
description: Entity tag for the resource
content:
'*/*':
schema:
type: string
format: binary
'404':
$ref: '#/components/responses/NotFound'
put:
summary: Upload/Update Resource
description: |
Creates a new file or completely replaces the content of an existing file. This is the primary method
for uploading files to the WebDAV server. The entire file content must be provided in the request body.
operationId: uploadResource
tags:
- Resource Operations
parameters:
- $ref: '#/components/parameters/PathParam'
- name: X-OC-Mtime
in: header
description: Custom modification time (Unix timestamp)
schema:
type: integer
example: 1692369418
requestBody:
required: true
content:
'*/*':
schema:
type: string
format: binary
responses:
'201':
description: File created successfully
'204':
description: File updated successfully
delete:
summary: Delete Resource
description: |
Permanently deletes a file or folder from the WebDAV server. For folders, this operation
recursively deletes all contained files and subfolders.
operationId: deleteResource
tags:
- Resource Operations
parameters:
- $ref: '#/components/parameters/PathParam'
responses:
'204':
description: Resource deleted successfully
'404':
$ref: '#/components/responses/NotFound'
/dav/spaces/{resourceId}/{path}:
parameters:
- $ref: '#/components/parameters/ResourceId'
- $ref: '#/components/parameters/PathParam'
post:
summary: WebDAV Operations (PROPFIND, PROPPATCH, MKCOL, etc.)
description: |
This endpoint handles various WebDAV methods using POST with method override headers.
The specific WebDAV method is indicated by the X-HTTP-Method-Override header.
**Supported WebDAV Methods:**
- **PROPFIND**: Retrieve properties and metadata from resources
- **PROPPATCH**: Update properties on resources
- **MKCOL**: Create collections (directories)
- **COPY**: Copy resources to new locations
- **MOVE**: Move resources to new locations
- **LOCK**: Create locks on resources
- **UNLOCK**: Remove locks from resources
operationId: webdavOperation
tags:
- WebDAV Operations
parameters:
- name: X-HTTP-Method-Override
in: header
required: true
description: The WebDAV method to execute
schema:
type: string
enum: ['PROPFIND', 'PROPPATCH', 'MKCOL', 'COPY', 'MOVE', 'LOCK', 'UNLOCK']
- name: Depth
in: header
description: Depth for operations that support it (PROPFIND, COPY, LOCK)
schema:
type: string
enum: ['0', '1', 'infinity']
- name: Destination
in: header
description: Destination URI for COPY and MOVE operations
schema:
type: string
format: uri
- name: Overwrite
in: header
description: Whether to overwrite existing destination (COPY, MOVE)
schema:
type: string
enum: ['T', 'F']
- name: Lock-Token
in: header
description: Lock token for UNLOCK operations
schema:
type: string
- name: Timeout
in: header
description: Lock timeout for LOCK operations
schema:
type: string
example: "Second-3600"
requestBody:
description: Request body varies by WebDAV method
content:
application/xml:
schema:
oneOf:
- $ref: '#/components/schemas/PropfindRequest'
- $ref: '#/components/schemas/ProppatchRequest'
- $ref: '#/components/schemas/LockRequest'
examples:
propfind:
summary: PROPFIND request
value: |
<?xml version="1.0"?>
<d:propfind xmlns:d="DAV:">
<d:allprop/>
</d:propfind>
proppatch:
summary: PROPPATCH request
value: |
<?xml version="1.0"?>
<d:propertyupdate xmlns:d="DAV:" xmlns:oc="http://owncloud.org/ns">
<d:set>
<d:prop>
<oc:favorite>1</oc:favorite>
</d:prop>
</d:set>
</d:propertyupdate>
lock:
summary: LOCK request
value: |
<?xml version="1.0"?>
<d:lockinfo xmlns:d="DAV:">
<d:lockscope><d:exclusive/></d:lockscope>
<d:locktype><d:write/></d:locktype>
<d:owner>John Doe</d:owner>
</d:lockinfo>
responses:
'200':
description: Operation successful (LOCK)
content:
application/xml:
schema:
$ref: '#/components/schemas/LockResponse'
'201':
description: Resource created (MKCOL, COPY, MOVE)
'204':
description: Operation successful (PROPPATCH, UNLOCK, MOVE, COPY)
'207':
description: Multi-status response (PROPFIND, partial operations)
content:
application/xml:
schema:
$ref: '#/components/schemas/MultistatusResponse'
'400':
$ref: '#/components/responses/BadRequest'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
'423':
description: Resource is locked
content:
application/xml:
schema:
$ref: '#/components/schemas/DAVError'
patch:
summary: Upload File Chunk (TUS Protocol)
description: |
Uploads a chunk of data to an existing upload session. This is the core operation of the TUS
resumable upload protocol, allowing files to be uploaded in multiple chunks that can be
resumed if interrupted.
operationId: uploadFileChunk
tags:
- Upload Operations
parameters:
- name: Tus-Resumable
in: header
required: true
description: TUS protocol version
schema:
type: string
example: "1.0.0"
- name: Upload-Offset
in: header
required: true
description: Byte offset where this chunk should be written
schema:
type: integer
example: 0
- name: Content-Type
in: header
required: true
description: Must be application/offset+octet-stream
schema:
type: string
const: "application/offset+octet-stream"
requestBody:
required: true
content:
application/offset+octet-stream:
schema:
type: string
format: binary
responses:
'204':
description: Chunk uploaded successfully
headers:
Upload-Offset:
schema:
type: integer
description: Current upload offset after this chunk
'400':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/NotFound'
/dav/spaces/{resourceId}/{path}/upload:
parameters:
- $ref: '#/components/parameters/ResourceId'
- $ref: '#/components/parameters/PathParam'
post:
summary: Create Upload Session (TUS Protocol)
description: |
Creates a new resumable upload session using the TUS protocol. This endpoint is used to initiate
large file uploads that can be resumed if interrupted.
operationId: createUploadSession
tags:
- Upload Operations
parameters:
- name: Tus-Resumable
in: header
required: true
description: TUS protocol version
schema:
type: string
example: "1.0.0"
- name: Upload-Length
in: header
required: true
description: Total size of the file to be uploaded
schema:
type: integer
example: 1048576
- name: Upload-Metadata
in: header
description: Base64-encoded metadata key-value pairs
schema:
type: string
example: "filename dGVzdC50eHQ="
responses:
'201':
description: Upload session created successfully
headers:
Location:
schema:
type: string
format: uri
description: URL for upload operations
Tus-Resumable:
schema:
type: string
description: TUS protocol version
'400':
$ref: '#/components/responses/BadRequest'
'403':
$ref: '#/components/responses/Forbidden'
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: Bearer token authentication using JWT tokens
BasicAuth:
type: http
scheme: basic
description: Basic authentication (for development only)
parameters:
ResourceId:
name: resourceId
in: path
required: true
description: Unique identifier of the WebDAV resource/space
schema:
type: string
example: "storage-users-1$some-admin-user-id-0000-000000000000"
PathParam:
name: path
in: path
required: false
description: Relative path within the resource
schema:
type: string
example: "Documents/example.txt"
style: simple
explode: false
responses:
BadRequest:
description: Bad request - malformed request or invalid parameters
content:
application/xml:
schema:
$ref: '#/components/schemas/DAVError'
Forbidden:
description: Forbidden - insufficient permissions
content:
application/xml:
schema:
$ref: '#/components/schemas/DAVError'
NotFound:
description: Not found - resource does not exist
content:
application/xml:
schema:
$ref: '#/components/schemas/DAVError'
Conflict:
description: Conflict - request conflicts with current resource state
content:
application/xml:
schema:
$ref: '#/components/schemas/DAVError'
schemas:
PropfindRequest:
type: object
description: PROPFIND request body for property discovery
xml:
name: propfind
namespace: "DAV:"
ProppatchRequest:
type: object
description: PROPPATCH request body for property updates
xml:
name: propertyupdate
namespace: "DAV:"
LockRequest:
type: object
description: LOCK request body for resource locking
xml:
name: lockinfo
namespace: "DAV:"
LockResponse:
type: object
description: LOCK response body with lock information
xml:
name: prop
namespace: "DAV:"
MultistatusResponse:
type: object
description: Multi-status response for operations affecting multiple resources
xml:
name: multistatus
namespace: "DAV:"
DAVError:
type: object
description: WebDAV error response
xml:
name: error
namespace: "DAV:"
properties:
exception:
type: string
description: Exception class name
message:
type: string
description: Human-readable error message
tags:
- name: Resource Operations
description: Basic file and folder operations (GET, PUT, DELETE)
- name: WebDAV Operations
description: WebDAV-specific operations (PROPFIND, PROPPATCH, MKCOL, COPY, MOVE, LOCK, UNLOCK)
- name: Upload Operations
description: Resumable file upload operations (TUS protocol)
externalDocs:
description: WebDAV RFC 4918
url: https://datatracker.ietf.org/doc/html/rfc4918