Merge pull request 'Updates for WOPI section' from feature/wopi-updat…

…es into develop

Reviewed-on: https://git.onlyoffice.com/ONLYOFFICE/api.onlyoffice.com/pulls/84

CHANGELOG.md

@@ -1,5 +1,6 @@
 # Change Log
 
+- docs api: updated the WOPI section
 - docs api: added the information about calling editor methods in the frameworks
 - docs api: added the Checking PDF forms page
 - docspace backend: added the Removed user page

site/pages/Docs/Docs API/Get Started/How It Works/index.md

@@ -51,7 +51,7 @@ Please note, that ONLYOFFICE Docs includes the **document editor**, **document e
 
 ## Shard key
 
-Starting from version 8.1, the *shardkey* parameter is added to the URL *QueryString* when sending requests to the ONLYOFFICE Docs API, **document command service**, **document conversion service**, or **document builder service**. It is also added to the browser-server interaction during the collaborative editing as the [WOPISrc](../../Using%20WOPI/Overview/index.md#wopisrc) query parameter.
+Starting from version 8.1, the *shardkey* parameter is added to the URL *QueryString* when sending requests to the ONLYOFFICE Docs API, **document command service**, **document conversion service**, or **document builder service**. It is also added to the browser-server interaction during the collaborative editing as the [WOPISrc](../../Using%20WOPI/Key%20concepts/index.md#wopisrc) query parameter.
 
 The *key* field is used as a value. For example, *?shardkey=Khirz6zTPdfd7*. If there is no key in the body, you do not have to send it (for example, in the [getForgottenList](../../Additional%20API/Command%20service/getForgottenList/index.md) command).
 

site/pages/Docs/Docs API/More Information/Changelog/index.md

@@ -38,7 +38,7 @@ The list of changes of ONLYOFFICE Docs API.
 
 ## Version 8.0
 
-- Added the [WOPISrc](../../Using%20WOPI/Overview/index.md#wopisrc) query parameter to the requests from the browser to the server.
+- Added the [WOPISrc](../../Using%20WOPI/Key%20concepts/index.md#wopisrc) query parameter to the requests from the browser to the server.
 - Added the [watermark](../../Additional%20API/Conversion%20API/Request/index.md#watermark) field to the conversion request.
 - Added the *pdf* document type to the [documentType](../../Usage%20API/Config/index.md#documenttype) parameter.
 - Added the [formsdataurl](../../Usage%20API/Callback%20handler/index.md#formsdataurl) parameter to the *Callback handler*.

site/pages/Docs/Docs API/Using WOPI/Host page/index.md

@@ -83,10 +83,10 @@ The host page must contain the following elements:
 
 ## Parameters
 
-| Name               | Type    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| ------------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| access\_token      | string  | An access token that the host will use to determine the identity and permissions of the issuer of a WOPI request.                                                                                                                                                                                                                                                                                                                                                                                                          |
-| access\_token\_ttl | integer | The time when an access token expires, represented as the number of milliseconds since January 1, 1970 UTC. It is recommended to set this parameter to 10 hours. This parameter can be also set to 0. This means for the client that the token expiry is either infinite or unknown. In this case, clients might disable any UI prompting users to refresh their sessions. This can lead to unexpected data loss due to access token expiry. So, this is strongly recommended to specify a value for *access\_token\_ttl*. |
-| docs\_api\_config  | string  | The optional [config](../../Usage%20API/Config/index.md) parameters for opening the editor via Docs API that are not supported by the WOPI protocol. For example, to enable the [forcesaving](../../Get%20Started/How%20It%20Works/Saving%20file/index.md#force-saving) functionality by clicking the **Save** button, the [editorConfig.customization.forcesave](../../Usage%20API/Config/Editor/Customization/index.md#forcesave) parameter must be passed in this object.                                               |
+| Name               | Type    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| ------------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| access\_token      | string  | An [access token](../Key%20concepts/index.md#access-token) that the host will use to determine the identity and permissions of the issuer of a WOPI request.                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| access\_token\_ttl | integer | The time when an [access token expires](../Key%20concepts/index.md#the-access_token_ttl-property), represented as the number of milliseconds since January 1, 1970 UTC. It is recommended to set this parameter to 10 hours. This parameter can be also set to 0. This means for the client that the token expiry is either infinite or unknown. In this case, clients might disable any UI prompting users to refresh their sessions. This can lead to unexpected data loss due to access token expiry. So, this is strongly recommended to specify a value for *access\_token\_ttl*. |
+| docs\_api\_config  | string  | The optional [config](../../Usage%20API/Config/index.md) parameters for opening the editor via Docs API that are not supported by the WOPI protocol. For example, to enable the [forcesaving](../../Get%20Started/How%20It%20Works/Saving%20file/index.md#force-saving) functionality by clicking the **Save** button, the [editorConfig.customization.forcesave](../../Usage%20API/Config/Editor/Customization/index.md#forcesave) parameter must be passed in this object.                                                                                                           |
 
 Further information about building a host page can be found [here](https://docs.microsoft.com/en-us/microsoft-365/cloud-storage-partner-program/online/hostpage).

site/pages/Docs/Docs API/Using WOPI/Key concepts/index.md

@@ -0,0 +1,61 @@
+---
+order: -9
+---
+
+Learn the following concepts that are vital to understand the requirements for integrating with WOPI clients. More information can be found [here](https://learn.microsoft.com/en-us/microsoft-365/cloud-storage-partner-program/rest/concepts).
+
+## File ID
+
+A file ID is a string that represents a file or folder being operated on using WOPI operations. A host must issue a unique ID for any file used by a WOPI client. The client will include the file ID when making requests to the WOPI host. So, a host must be able to use the file ID to locate a particular file.
+
+A file ID must:
+
+- represent a single file;
+- be a URL-safe string, because IDs are passed in URLs, principally via the [WOPISrc](#wopisrc) parameter;
+- remain the same when the file is edited;
+- remain the same when the file is moved or renamed;
+- remain the same when any ancestor container, including the parent container, is renamed;
+- in the case of shared files, the ID for a given file must be the same for every user that accesses the file.
+
+## Access token
+
+An access token is a string used by the host to determine the identity and permissions of the issuer of a WOPI request.
+
+The WOPI host that stores the file has the information about user permissions. For this reason, the WOPI host must provide an access token that the client then passes back to it on subsequent WOPI requests. When the WOPI host receives the token, it either validates it, or responds with an appropriate HTTP status code if the token is invalid or unauthorized.
+
+In the online office, an access token is generated by the host and passed to the client using the `access_token` parameter before the first WOPI request.
+
+WOPI access tokens must adhere to the guidelines described [here](https://learn.microsoft.com/en-us/microsoft-365/cloud-storage-partner-program/rest/concepts#access-token).
+
+## The access_token_ttl property
+
+The `access_token_ttl` property tells a WOPI client when an access token expires, represented as the number of milliseconds since January 1, 1970 UTC (the date epoch in JavaScript). Despite its misleading name, it doesn't represent a time duration for which the access token is valid. The `access_token_ttl` is never used by itself; it's always attached to a specific access token.
+
+We recommend using an `access_token_ttl` value that makes the access token valid for 10 hours. Hosts can also set the `access_token_ttl` value to `0`. This effectively tells the client that the token expiry is either infinite or unknown. In this case, clients might disable any UI prompting users to refresh their sessions. This can lead to unexpected data loss due to access token expiry. So, we strongly recommend specifying a value for `access_token_ttl`.
+
+## Lock
+
+A lock is a conceptual construct that's associated with a file. Locks serve two purposes in WOPI:
+
+- A lock prevents anyone that doesn't have a valid lock ID from making changes to a file. A WOPI client locks files prior to editing them to prevent other entities from changing the file while the client is also editing them.
+- A lock is also used to store a small bit of temporary data associated with a file. This metadata is called the lock ID and is a string with a maximum length of 1024 ASCII characters.
+
+Therefore, WOPI locks must:
+
+- be associated with a single file;
+- contain a lock ID of maximum length 1024 ASCII characters;
+- prevent all changes to that file unless a proper lock ID is provided;
+- expire after 30 minutes unless refreshed ([RefreshLock](../WOPI%20REST%20API/RefreshLock/index.md));
+- not be associated with a particular user.
+
+All WOPI operations that modify files, such as [PutFile](../WOPI%20REST%20API/PutFile/index.md), include a lock ID as a parameter in their request. Usually the expected lock ID is passed in the `X-WOPI-Lock` request header.
+
+WOPI requires that hosts compare the lock ID passed in a WOPI request with the lock ID currently on a file and respond appropriately when the lock IDs don't match. In particular, WOPI clients expect that when a lock ID does not match the current lock, the host sends back the current lock ID in the `X-WOPI-Lock` response header. This behavior is critical, because WOPI clients use the current lock ID in order to determine what further WOPI calls to make to the host.
+
+## WOPISrc
+
+The WOPISrc (WOPI Source) is the URL that runs WOPI operations on a file. It's a combination of the Files endpoint URL for the host, along with a particular [file ID](#file-id). The WOPISrc doesn't include an [access token](#access-token).
+
+Starting from version 8.0, the WOPISrc query parameter is added to the requests from the browser to the server. This allows you to create several independent instances of ONLYOFFICE. Load balancing requests with WOPISrc ensure that collaborative editing works correctly: all users editing the same document are served by the same server.
+
+For WOPI, the parameter sent by the integrator is used. For Docs API, the [shardkey](../../Get%20Started/How%20It%20Works/index.md#shard-key) parameter is used.

site/pages/Docs/Docs API/Using WOPI/Overview/index.md

@@ -1,11 +1,13 @@
 ---
-order: -9
+order: -11
 ---
 
 Starting from version 6.4, ONLYOFFICE Docs offers support for the **Web Application Open Platform Interface Protocol (WOPI)** - a REST-based protocol that is used to integrate your application with an online office. WOPI operations allow you to open files stored on a server, edit and save them.
 
 This documentation describes:
 
+- WOPI protocol [configuration parameters](../Config/index.md);
+- [key concepts](../Key%20concepts/index.md) that are vital to understand the requirements for integrating with WOPI clients;
 - file properties that can be specified via [WOPI discovery](../WOPI%20discovery/index.md);
 - a [host page](../Host%20page/index.md) that must be built to create an iframe element within the online office;
 - [proof keys](../Proof%20keys/index.md) which are used to check that the request is received from the online office;
@@ -97,9 +99,3 @@ Follow the steps below to configure the ONLYOFFICE Docs [IP filter](https://help
    ``` sh
    supervisorctl restart all
    ```
-
-## WOPISrc
-
-Starting from version 8.0, the WOPISrc query parameter is added to the requests from the browser to the server. This allows you to create several independent instances of ONLYOFFICE. Load balancing requests with WOPISrc ensure that collaborative editing works correctly: all users editing the same document are served by the same server.
-
-For WOPI, the parameter sent by the integrator is used. For Docs API, the [shardkey](../../Get%20Started/How%20It%20Works/index.md#shard-key) parameter is used.

site/pages/Docs/Docs API/Using WOPI/WOPI REST API/CheckFileInfo/index.md

@@ -4,15 +4,15 @@ The *CheckFileInfo* operation must be implemented for all WOPI actions. This ope
 
 ## Parameters
 
-| Name     | Type   | Description                                                         |
-| -------- | ------ | ------------------------------------------------------------------- |
-| file\_id | string | The ID of a file managed by the host. This string must be URL safe. |
+| Name     | Type   | Description                                                                                                  |
+| -------- | ------ | ------------------------------------------------------------------------------------------------------------ |
+| file\_id | string | The [ID of a file](../../Key%20concepts/index.md#file-id) managed by the host. This string must be URL safe. |
 
 ## Query parameters
 
-| Name          | Type   | Description                                                                        |
-| ------------- | ------ | ---------------------------------------------------------------------------------- |
-| access\_token | string | An access token that the host uses to determine whether the request is authorized. |
+| Name          | Type   | Description                                                                                                                      |
+| ------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------- |
+| access\_token | string | An [access token](../../Key%20concepts/index.md#access-token) that the host uses to determine whether the request is authorized. |
 
 ## Request headers
 
@@ -22,6 +22,8 @@ The *CheckFileInfo* operation must be implemented for all WOPI actions. This ope
 
 ## Required response properties
 
+> Please note that the default value for any response string value is the empty string.
+
 ### BaseFileName
 
 A name of the file, including extension, without a path. Used for display in user interface (UI), and determining the extension of the file.

site/pages/Docs/Docs API/Using WOPI/WOPI REST API/GetFile/index.md

@@ -4,15 +4,15 @@ Retrieves a file from a host for the `HTTP://server/<...>/wopi*/files/<id>/conte
 
 ## Parameters
 
-| Name     | Type   | Description                        |
-| -------- | ------ | ---------------------------------- |
-| file\_id | string | The file ID that must be URL safe. |
+| Name     | Type   | Description                                                                 |
+| -------- | ------ | --------------------------------------------------------------------------- |
+| file\_id | string | The [file ID](../../Key%20concepts/index.md#file-id) that must be URL safe. |
 
 ## Query parameters
 
-| Name          | Type   | Description                                                                        |
-| ------------- | ------ | ---------------------------------------------------------------------------------- |
-| access\_token | string | An access token that the host uses to determine whether the request is authorized. |
+| Name          | Type   | Description                                                                                                                      |
+| ------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------- |
+| access\_token | string | An [access token](../../Key%20concepts/index.md#access-token) that the host uses to determine whether the request is authorized. |
 
 ## Request headers
 

site/pages/Docs/Docs API/Using WOPI/WOPI REST API/Lock/index.md

@@ -1,6 +1,6 @@
 `POST /wopi/files/(file_id)`
 
-Locks a file for editing by the WOPI client application instance that requested the lock.
+Locks a file for editing by the WOPI client application instance that requested the [lock](../../Key%20concepts/index.md#lock).
 
 This operation works as follows:
 
@@ -12,15 +12,15 @@ This operation works as follows:
 
 ## Parameters
 
-| Name     | Type   | Description                        |
-| -------- | ------ | ---------------------------------- |
-| file\_id | string | The file ID that must be URL safe. |
+| Name     | Type   | Description                                                                 |
+| -------- | ------ | --------------------------------------------------------------------------- |
+| file\_id | string | The [file ID](../../Key%20concepts/index.md#file-id) that must be URL safe. |
 
 ## Query parameters
 
-| Name          | Type   | Description                                                                            |
-| ------------- | ------ | -------------------------------------------------------------------------------------- |
-| access\_token | string | An access token that the host will use to determine whether the request is authorized. |
+| Name          | Type   | Description                                                                                                                          |
+| ------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------ |
+| access\_token | string | An [access token](../../Key%20concepts/index.md#access-token) that the host will use to determine whether the request is authorized. |
 
 ## Request headers