Skip to content

Commit

Permalink
Docs api: fixes for REST API methods pages
Browse files Browse the repository at this point in the history
  • Loading branch information
@ovchinnikova-natalya
ovchinnikova-natalya committed Jul 19, 2024
1 parent 352a9fe commit 8d26ebc
Show file tree
Hide file tree
Showing 8 changed files with 390 additions and 126 deletions.
432 changes: 348 additions & 84 deletions site/pages/Docs/Docs API/Using WOPI/WOPI REST API/CheckFileInfo/index.md
View file

Large diffs are not rendered by default.

12 changes: 6 additions & 6 deletions site/pages/Docs/Docs API/Using WOPI/WOPI REST API/GetFile/index.md
View file
Original file line number Diff line number Diff line change
@@ -1,33 +1,33 @@
**GET /wopi/files/*(file\_id)*/contents**

Requests a message to retrieve a file for the *HTTP://server/<...>/wopi\*/files/\<id>/contents* operation.
Requests a message to retrieve a file for the `HTTP://server/<...>/wopi*/files/<id>/contents` operation.

The response body must contain the full file contents in the binary format.

Parameters
### Parameters

| Name | Description | Type |
| -------- | ---------------------------------- | ------ |
| file\_id | The file ID that must be URL safe. | string |

Query parameters
### Query parameters

| Name | Description | Type |
| ------------- | -------------------------------------------------------------------------------------- | ------ |
| access\_token | An access token that the host will use to determine whether the request is authorized. | string |

Request headers
### Request headers

| Name | Description | Type | Presence |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- | -------- |
| X-WOPI-MaxExpectedSize | The maximum expected size of the file being requested. The host should use the maximum value of a 4-byte integer if this value is not set in the request. If the file requested is larger than this value, the host must respond with **412 Precondition Failed**. | integer | optional |

Response headers
### Response headers

| Name | Description | Type | Presence |
| ------------------ | ----------------- | ------ | -------- |
| X-WOPI-ItemVersion | The file version. | string | optional |

Response body
### Response body

The response body must be the full binary contents of the file.
8 changes: 4 additions & 4 deletions site/pages/Docs/Docs API/Using WOPI/WOPI REST API/Lock/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,26 +10,26 @@ This operation works as follows:
4. In all other cases, the host must return **409 Conflict** (*"lock mismatch"*) and include the **X-WOPI-Lock** response header containing the value of the current lock on the file.
5. In the case where the file is locked by a third-party client, hosts should still always include the current lock ID in the **X-WOPI-Lock** response header.

Parameters
### Parameters

| Name | Description | Type |
| -------- | ---------------------------------- | ------ |
| file\_id | The file ID that must be URL safe. | string |

Query parameters
### Query parameters

| Name | Description | Type |
| ------------- | -------------------------------------------------------------------------------------- | ------ |
| access\_token | An access token that the host will use to determine whether the request is authorized. | string |

Request headers
### Request headers

| Name | Description | Type | Presence |
| --------------- | -------------------------------------------------------------------- | ------ | -------- |
| X-WOPI-Override | The requested operation from the WOPI server (*LOCK*). | string | required |
| X-WOPI-Lock | The lock ID that the host must use to identify the lock on the file. | string | required |

Response headers
### Response headers

| Name | Description | Type | Presence |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | -------- |
Expand Down
14 changes: 7 additions & 7 deletions site/pages/Docs/Docs API/Using WOPI/WOPI REST API/PutFile/index.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
**POST /wopi/files/*(file\_id)*/contents**

Requests a message to update a file for the *HTTP://server/<...>/wopi\*/files/\<id>/contents* operation.
Requests a message to update a file for the `HTTP://server/<...>/wopi*/files/<id>/contents` operation.

The request body must contain the full file contents in the binary format.

Expand All @@ -11,34 +11,34 @@ This operation works as follows:
3. If the file is **unlocked**, the host must check the current size of the file. If it is 0 bytes, the **PutFile** request should be considered valid and should proceed. If it is any value other than 0 bytes, or is missing altogether, the host should respond with **409 Conflict**.
4. In the case where the file is locked by a third-party client, hosts should still always include the current lock ID in the **X-WOPI-Lock** response header.

Parameters
### Parameters

| Name | Description | Type |
| -------- | ---------------------------------- | ------ |
| file\_id | The file ID that must be URL safe. | string |

Query parameters
### Query parameters

| Name | Description | Type |
| ------------- | -------------------------------------------------------------------------------------- | ------ |
| access\_token | An access token that the host will use to determine whether the request is authorized. | string |

Request headers
### Request headers

| Name | Description | Type | Presence |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | -------- |
| X-WOPI-Override | The requested operation from the WOPI server (*PUT*). | string | required |
| X-WOPI-Lock | The lock ID that the host must use to identify the lock on the file. | string | optional |
| X-WOPI-Editors | All the users who contributed changes to the document in this **PutFile** request ([UserId](/editors/wopi/restapi/checkfileinfo#UserId) values delimited by commas). | string | optional |
| X-WOPI-Editors | All the users who contributed changes to the document in this **PutFile** request ([UserId](../CheckFileInfo/index.md#userid) values delimited by commas). | string | optional |
| X-LOOL-WOPI-IsModifiedByUser | Indicates whether the user has modified the document before the save (**"true"**), or if they just pressed the **Save** button without any modification (**"false"**). | string | optional |
| X-LOOL-WOPI-IsAutosave | Indicates whether the **PutFile** is triggered by autosave (**"true"**) or by explicit user operation (**Save** button or menu entry) (**"false"**). | string | optional |
| X-LOOL-WOPI-IsExitSave | Indicates whether an automatic save will be triggered when the document gets cleaned up from memory (e.g. when all users disconnect) (**"true"**) or not (**"false"**). | string | optional |

Request body
### Request body

The request body must be the full binary contents of the file.

Response headers
### Response headers

| Name | Description | Type | Presence |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | -------- |
Expand Down
22 changes: 11 additions & 11 deletions site/pages/Docs/Docs API/Using WOPI/WOPI REST API/PutRelativeFile/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,51 +15,51 @@ This operation works as follows:

4. Finally, the host creates a new file that has a legal name and does not overwrite any existing files, while preserving the file extension.

Parameters
### Parameters

| Name | Description | Type |
| -------- | ---------------------------------- | ------ |
| file\_id | The file ID that must be URL safe. | string |

Query parameters
### Query parameters

| Name | Description | Type |
| ------------- | -------------------------------------------------------------------------------------- | ------ |
| access\_token | An access token that the host will use to determine whether the request is authorized. | string |

Request headers
### Request headers

| Name | Description | Type | Presence |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------- | ------- | -------- |
| X-WOPI-Override | The requested operation from the WOPI server (*PUT\_RELATIVE*). | string | required |
| X-WOPI-SuggestedTarget | A file extension or a full file name, including the file extension in the format of the UTF-7 encoded string. | string | required |
| X-WOPI-Size | The size of the file in bytes. | integer | optional |
| X-WOPI-FileConversion | Indicates that the request is being made in the context of [binary document conversion](/editors/wopi/editingbinary). | boolean | optional |
| X-WOPI-FileConversion | Indicates that the request is being made in the context of [binary document conversion](../../Editing%20binary%20documents/index.md). | boolean | optional |

Request body
### Request body

The request body must contain the full file contents in the binary format.

Response headers
### Response headers

| Name | Description | Type | Presence |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | -------- |
| X-WOPI-Lock | The lock ID identifying the current lock on the file. This header must always be included when responding to the request with **409 Conflict**. It should not be included when responding to the request with **200 OK**. | string | optional |
| X-WOPI-LockFailureReason | The cause of the lock failure. This header may be included when responding to the request with **409 Conflict**. It must only be used for logging purposes. | string | optional |

Response body
### Response body

| Name | Description | Type | Presence |
| ----------- | --------------------------------------------------------------------------------------------------------------------------------- | ------ | -------- |
| Name | The file name, including extension, without a path. | string | required |
| Url | URI of the form *http\://server/<...>/wopi/files/(file\_id)?access\_token=(access token)*, of the newly created file on the host. | string | required |
| HostViewUrl | URI to a host page that loads the [view](/editors/wopi/discovery#view) WOPI action for the newly created file. | string | optional |
| HostEditUrl | URI to a host page that loads [edit](/editors/wopi/discovery#edit) action for the newly created file. | string | optional |
| HostViewUrl | URI to a host page that loads the [view](../../WOPI%20discovery/index.md#wopi-actions) WOPI action for the newly created file. | string | optional |
| HostEditUrl | URI to a host page that loads [edit](../../WOPI%20discovery/index.md#wopi-actions) action for the newly created file. | string | optional |

## Save Copy As

Starting from version 8.1, the *Save Copy As* functionality is added to the WOPI protocol through the *PutRelativeFile* operation. In the ONLYOFFICE Docs API, this action is implemented as the [onRequestSaveAs](/editors/config/events#onRequestSaveAs) event.
Starting from version 8.1, the *Save Copy As* functionality is added to the WOPI protocol through the *PutRelativeFile* operation. In the ONLYOFFICE Docs API, this action is implemented as the [onRequestSaveAs](../../../Usage%20API/Config/Events/index.md#onrequestsaveas) event.

When the *PutRelativeFile* operation is executed to save a copy of the current file, the *X-WOPI-FileConversion* header is not sent in the request.

To restrict the *Save Copy As* functionality, set the [UserCanNotWriteRelative](/editors/wopi/restapi/checkfileinfo#UserCanNotWriteRelative) property in *CheckFileInfo* to *true*.
To restrict the *Save Copy As* functionality, set the [UserCanNotWriteRelative](../CheckFileInfo/index.md#usercannotwriterelative) property in *CheckFileInfo* to *true*.
10 changes: 5 additions & 5 deletions site/pages/Docs/Docs API/Using WOPI/WOPI REST API/RefreshLock/index.md
View file
Original file line number Diff line number Diff line change
@@ -1,33 +1,33 @@
**POST /wopi/files/*(file\_id)***

Refreshes the lock on a file by resetting its automatic expiration timer to 30 minutes. This lock will expire automatically after 30 minutes unless it is changed by the [Unlock](/editors/wopi/restapi/unlock) or another *RefreshLock* operations.
Refreshes the lock on a file by resetting its automatic expiration timer to 30 minutes. This lock will expire automatically after 30 minutes unless it is changed by the [Unlock](../Unlock/index.md) or another *RefreshLock* operations.

This operation works as follows:

1. The WOPI host checks if a file is currently locked or not.
2. If the file is **unlocked**, or if the file is currently **locked** and the **X-WOPI-Lock** value does not match the lock currently on the file, the host must return **409 Conflict** (*"lock mismatch"*) and include the **X-WOPI-Lock** response header containing the value of the current lock on the file. In the case where the file is unlocked, the host must set **X-WOPI-Lock** to the empty string.
3. In the case where the file is locked by a third-party client, hosts should still always include the current lock ID in the **X-WOPI-Lock** response header.

Parameters
### Parameters

| Name | Description | Type |
| -------- | ---------------------------------- | ------ |
| file\_id | The file ID that must be URL safe. | string |

Query parameters
### Query parameters

| Name | Description | Type |
| ------------- | -------------------------------------------------------------------------------------- | ------ |
| access\_token | An access token that the host will use to determine whether the request is authorized. | string |

Request headers
### Request headers

| Name | Description | Type | Presence |
| --------------- | -------------------------------------------------------------------- | ------ | -------- |
| X-WOPI-Override | The requested operation from the WOPI server (*REFRESH\_LOCK*). | string | required |
| X-WOPI-Lock | The lock ID that the host must use to identify the lock on the file. | string | required |

Response headers
### Response headers

| Name | Description | Type | Presence |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | -------- |
Expand Down
Loading

0 comments on commit 8d26ebc

Please sign in to comment.