Merge pull request #1396 from nextcloud/docs/enhance

Author: juliusknorr

README.md

@@ -5,15 +5,15 @@
 
 Deck is a kanban style organization tool aimed at personal planning and project organization for teams integrated with Nextcloud.
 
-- :inbox_tray: Add your tasks to cards and put them in order
-- :page_facing_up: Write down additional notes in markdown
-- :bookmark: Assign labels for even better organization
-- :busts_in_silhouette: Share with your team, friends or family
-- :family: Integrates with the [Circles](https://github.com/nextcloud/circles) app!
-- :paperclip: Attach files and embed them in your markdown description
-- :speech_balloon: Discuss with your team using comments
-- :zap: Keep track of changes in the activity stream
-- :rocket: Get your project organized
+- Add your tasks to cards and put them in order
+- Write down additional notes in markdown
+- Assign labels for even better organization
+- Share with your team, friends or family
+- Integrates with the [Circles](https://github.com/nextcloud/circles) app!
+- Attach files and embed them in your markdown description
+- Discuss with your team using comments
+- Keep track of changes in the activity stream
+- Get your project organized
 
 ### Mobile apps
 

docs/API-Nextcloud.md

@@ -1,5 +1,34 @@
 # Nextcloud APIs
 
+## Capabilities
+
+The [Nextcloud Capabilities API](https://docs.nextcloud.com/server/latest/developer_manual/client_apis/OCS/ocs-api-overview.html#capabilities-api) provides the following information for the Deck app:
+
+- `version` Current version of the Deck app running
+- `canCreateBoards` Ability of the current user to create new boards for themselves
+
+```
+{
+  "ocs": {
+    "meta": {
+      "status": "ok",
+      "statuscode": 200,
+      "message": "OK"
+    },
+    "data": {
+      "capabilities": {
+        "deck": {
+          "version": "0.8.0",
+          "canCreateBoards": true
+        },
+      }
+    }
+  }
+}
+```
+
+
+
 ## Available sharees
 
 When sharing a board to a user, group or circle, the possible sharees can be obtained though the files_sharing API.

docs/API.md

@@ -5,6 +5,7 @@ The REST API provides access for authenticated users to their data inside the De
 
 - All requests require a `OCS-APIRequest` HTTP header to be set to `true` and a `Content-Type` of `application/json`.
 - The API is located at https://nextcloud.local/index.php/apps/deck/api/v1.0
+- All request parameters are required, unless otherwise specified
 
 ## Naming
 
@@ -20,7 +21,7 @@ The REST API provides access for authenticated users to their data inside the De
 
 ### 400 Bad request
 
-In case the request is invalid, e.g. because a parameter is missing, a 400 error will be returned:
+In case the request is invalid, e.g. because a parameter is missing or an invalid value has been transmitted, a 400 error will be returned:
 
 ```json
 {
@@ -40,6 +41,12 @@ In any case a user doesn't have access to a requested entity, a 403 error will b
 }
 ```
 
+## Formats
+
+### Date
+
+Datetime values in request data need to be provided in ISO-8601. Example: 2020-01-20T09:52:43+00:00
+
 ## Headers
 
 ### If-Modified-Since
@@ -51,7 +58,7 @@ The supported date formats are:
 * (obsolete) RFC 850:          `Sunday, 03-Aug-19 10:34:12 GMT`
 * (obsolete) ANSI C asctime(): `Sun Aug  3 10:34:12 2019`
 
-It is highly recommended to only use the IMF-fixdate format.
+It is highly recommended to only use the IMF-fixdate format. Note that according to [RFC2616](https://tools.ietf.org/html/rfc2616#section-3.3) all HTTP date/time stamps MUST be represented in Greenwich Mean Time (GMT), without exception.
 
 Example curl request:
 
@@ -197,6 +204,10 @@ Returns an array of board items
 }
 ```
 
+##### 403 Forbidden
+
+A 403 response might be returned if the users ability to create new boards has been disabled by the administrator. For checking this before, see the `canCreateBoards` value in the [Nextcloud capabilties](./API-Nextcloud.md).
+
 ### GET /boards/{boardId} - Get board details
 
 #### Request parameters
@@ -548,7 +559,7 @@ The board list endpoint supports setting an `If-Modified-Since` header to limit
    "owner":"admin",
    "order":999,
    "archived":false,
-   "duedate":null,
+   "duedate": "2019-12-24T19:29:30+00:00",
    "deletedAt":0,
    "commentsUnread":0,
    "id":10,
@@ -576,7 +587,7 @@ The board list endpoint supports setting an `If-Modified-Since` header to limit
 | description | String    | The markdown description of the card                 |
 | type        | String    | Type of the card (for later use) use 'plain' for now |
 | order       | Integer   | Order for sorting the stacks                         |
-| duedate     | timestamp | The duedate of the card or null                      |
+| duedate     | timestamp | The ISO-8601 formatted duedate of the card or null   |
 
 
 ```
@@ -585,7 +596,7 @@ The board list endpoint supports setting an `If-Modified-Since` header to limit
    "description": "A card description",
    "type": "plain",
    "order": 999,
-   "duedate": null,
+   "duedate": "2019-12-24T19:29:30+00:00",
 }
 ```
 

lib/Capabilities.php

@@ -23,10 +23,23 @@
 
 namespace OCA\Deck;
 
+use OCA\Deck\Service\PermissionService;
+use OCP\App\IAppManager;
 use OCP\Capabilities\ICapability;
 
 class Capabilities implements ICapability {
 
+	/** @var IAppManager */
+	private $appManager;
+	/**  @var PermissionService */
+	private $permissionService;
+
+
+	public function __construct(IAppManager $appManager, PermissionService $permissionService) {
+		$this->appManager = $appManager;
+		$this->permissionService = $permissionService;
+	}
+
 	/**
 	 * Function an app uses to return the capabilities
 	 *
@@ -36,7 +49,8 @@ class Capabilities implements ICapability {
 	public function getCapabilities() {
 		return [
 			'deck' => [
-				'version' => \OC::$server->getAppManager()->getAppVersion('deck')
+				'version' => $this->appManager->getAppVersion('deck'),
+				'canCreateBoards' => $this->permissionService->canCreate()
 			]
 		];
 	}