Merge pull request #1396 from nextcloud/docs/enhance

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()
  ]
  ];
  }