Skip to content

Commit

Permalink
fixed docs for app-cfg and preferences-cfg (#167)
Browse files Browse the repository at this point in the history
  • Loading branch information
@bigcat88
bigcat88 authored Dec 18, 2023
1 parent 253fd43 commit d4610dc
Show file tree
Hide file tree
Showing 4 changed files with 146 additions and 64 deletions.
90 changes: 62 additions & 28 deletions docs/tech_details/api/appconfig.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,9 @@ ExApp AppConfig API is similar to the standard Nextcloud **appconfig** API.
Set app config value
^^^^^^^^^^^^^^^^^^^^

Set ExApp config value.
Set or update ExApp config value.

.. note:: when ``sensitive`` is not specified during updating value, it will be not changed to default.

OCS endpoint: ``POST /apps/app_api/api/v1/ex-app/config``

Expand All @@ -17,38 +19,39 @@ Request data
.. code-block:: json
{
"key": "key",
"value": "value"
"sensitive": "sensitive flag affecting the visibility of the value (true/false, default: false)"
"configKey": "key",
"configValue": "value"
"sensitive": "sensitive flag affecting the visibility of the value (0/1, default: 0)"
}
Response data
*************

On success, ExAppConfig object is returned.
On error OCS Bad Request is returned.

.. code-block:: json
{
"key": "key",
"value": "value"
"sensitive": "true/false"
}
Update app config value or sensitive flag
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Update existing ExApp config value or sensitive flag.
It's the same endpoint as for setting config value.

OCS endpoint: ``POST /apps/app_api/api/v1/ex-app/config``

.. code-block:: json
{
"key": "key",
"value": "value"
"sensitive": "(optional), will not be updated if not provided"
"ocs":
{
"meta":
{
"status":"ok",
"statuscode":100,
"message":"OK",
"totalitems":"",
"itemsperpage":""
},
"data":
{
"id":1084,
"appid":"app_id",
"configkey":"key",
"configvalue":"value",
"sensitive":1
}
}
}
Get app config values
Expand All @@ -74,11 +77,25 @@ List of ExApp config values are returned.

.. code-block:: json
[
{ "configkey": "key1", "configvalue": "value1" },
{ "configkey": "key2", "configvalue": "value2" },
{ "configkey": "key3", "configvalue": "value3" },
]
{
"ocs":
{
"meta":
{
"status":"ok",
"statuscode":100,
"message":"OK",
"totalitems":"",
"itemsperpage":""
},
"data":[
{
"configkey":"test_key",
"configvalue":"123"
}
]
}
}
Delete app config values
^^^^^^^^^^^^^^^^^^^^^^^^
Expand All @@ -100,3 +117,20 @@ Response
********

Returns the number of configuration values removed.

.. code-block:: json
{
"ocs":
{
"meta":
{
"status":"ok",
"statuscode":100,
"message":"OK",
"totalitems":"",
"itemsperpage":""
},
"data":1
}
}
86 changes: 78 additions & 8 deletions docs/tech_details/api/preferences.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,13 +9,13 @@ It's a user specific settings.
Set user config value
^^^^^^^^^^^^^^^^^^^^^

Set or update config value for **current authenticated user**.

OCS endpoint: ``POST /apps/app_api/api/v1/ex-app/preference``

Request data
************

Set config value for **current authenticated user**.

.. code-block:: json
{
Expand All @@ -27,35 +27,90 @@ Response data
*************

On success ExAppPreference object is returned.
If config value is not set - ``null`` is returned.
On error OCS Bad Request is returned.

.. code-block:: json
{
"ocs":
{
"meta":
{
"status":"ok",
"statuscode":100,
"message":"OK",
"totalitems":"",
"itemsperpage":""
},
"data":
{
"id":983,
"appid":"app_id",
"configkey":"test key",
"configvalue":"123",
"sensitive":0
}
}
}
Get user config values
^^^^^^^^^^^^^^^^^^^^^^

Get config values for **current authenticated user**.

OCS endpoint: ``POST /apps/app_api/api/v1/ex-app/preference/get-values``

Request data
************

Get config values for **current authenticated user**.

.. code-block:: json
{
"configKeys": ["key1", "key2", "key3"]
}
Response data
*************

List of ExApp preferences values are returned.

.. code-block:: json
{
"ocs":
{
"meta":
{
"status":"ok",
"statuscode":100,
"message":"OK",
"totalitems":"",
"itemsperpage":""
},
"data":[
{
"configkey":"test key",
"configvalue":"123"
},
{
"configkey":"test key2",
"configvalue":"321"
}
]
}
}
Delete user config values
^^^^^^^^^^^^^^^^^^^^^^^^^

Delete config values for **current authenticated user**.

OCS endpoint: ``DELETE /apps/app_api/api/v1/ex-app/preference``

Request data
************

Delete config values for **current authenticated user**.

.. code-block:: json
{
Expand All @@ -65,4 +120,19 @@ Delete config values for **current authenticated user**.
Response
********

Returns the number of configuration values removed.
.. code-block:: json
{
"ocs":
{
"meta":
{
"status":"ok",
"statuscode":100,
"message":"OK",
"totalitems":"",
"itemsperpage":""
},
"data":2
}
}
15 changes: 2 additions & 13 deletions lib/Controller/AppConfigController.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,8 +22,8 @@ class AppConfigController extends OCSController {
protected $request;

public function __construct(
IRequest $request,
private ExAppConfigService $exAppConfigService,
IRequest $request,
private readonly ExAppConfigService $exAppConfigService,
) {
parent::__construct(Application::APP_ID, $request);

Expand All @@ -34,11 +34,7 @@ public function __construct(
* @PublicPage
* @NoCSRFRequired
*
* @param string $configKey
* @param mixed $configValue
* @param int|null $sensitive
* @throws OCSBadRequestException
* @return DataResponse
*/
#[AppAPIAuth]
#[PublicPage]
Expand All @@ -58,10 +54,6 @@ public function setAppConfigValue(string $configKey, mixed $configValue, ?int $s
/**
* @PublicPage
* @NoCSRFRequired
*
* @param array $configKeys
*
* @return DataResponse
*/
#[AppAPIAuth]
#[PublicPage]
Expand All @@ -76,11 +68,8 @@ public function getAppConfigValues(array $configKeys): DataResponse {
* @PublicPage
* @NoCSRFRequired
*
* @param array $configKeys
*
* @throws OCSBadRequestException
* @throws OCSNotFoundException
* @return DataResponse
*/
#[AppAPIAuth]
#[PublicPage]
Expand Down
19 changes: 4 additions & 15 deletions lib/Controller/PreferencesController.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,9 +23,9 @@ class PreferencesController extends OCSController {
protected $request;

public function __construct(
IRequest $request,
private IUserSession $userSession,
private ExAppPreferenceService $exAppPreferenceService,
IRequest $request,
private readonly IUserSession $userSession,
private readonly ExAppPreferenceService $exAppPreferenceService,
) {
parent::__construct(Application::APP_ID, $request);

Expand All @@ -36,11 +36,7 @@ public function __construct(
* @PublicPage
* @NoCSRFRequired
*
* @param string $configKey
* @param mixed $configValue
*
* @throws OCSBadRequestException
* @return DataResponse
*/
#[AppAPIAuth]
#[PublicPage]
Expand All @@ -53,18 +49,14 @@ public function setUserConfigValue(string $configKey, mixed $configValue): DataR
$appId = $this->request->getHeader('EX-APP-ID');
$result = $this->exAppPreferenceService->setUserConfigValue($userId, $appId, $configKey, $configValue);
if ($result instanceof ExAppPreference) {
return new DataResponse(1, Http::STATUS_OK);
return new DataResponse($result, Http::STATUS_OK);
}
throw new OCSBadRequestException('Failed to set user config value');
}

/**
* @PublicPage
* @NoCSRFRequired
*
* @param array $configKeys
*
* @return DataResponse
*/
#[AppAPIAuth]
#[PublicPage]
Expand All @@ -80,11 +72,8 @@ public function getUserConfigValues(array $configKeys): DataResponse {
* @PublicPage
* @NoCSRFRequired
*
* @param array $configKeys
*
* @throws OCSBadRequestException
* @throws OCSNotFoundException
* @return DataResponse
*/
#[AppAPIAuth]
#[PublicPage]
Expand Down

0 comments on commit d4610dc

Please sign in to comment.