From 35991b744896bbb724067dbf9a9b74d819b7310c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Julius=20H=C3=A4rtl?= Date: Tue, 6 Nov 2018 19:39:09 +0100 Subject: [PATCH] Add data examples to the docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Julius Härtl --- docs/API.md | 156 ++++++++++++++++++++- lib/Controller/AttachmentApiController.php | 3 +- 2 files changed, 152 insertions(+), 7 deletions(-) diff --git a/docs/API.md b/docs/API.md index 0a32e06fd..ddb792715 100644 --- a/docs/API.md +++ b/docs/API.md @@ -245,7 +245,7 @@ Returns an array of board items { "title": "Board title", "color": "ff0000", - "archived: false + "archived": false } ``` @@ -425,14 +425,33 @@ The board list endpoint supports setting an `If-Modified-Since` header to limit | --------- | ------- | ---------------------------------------------------- | | title | String | The title of the new stack | | type | String | Type of the card (for later use) use 'plain' for now | -| - - | Integer | Order for sorting the stacks | - - +| order | Integer | Order for sorting the stacks | #### Response +```json +{ + "title":"Test", + "description":null, + "stackId":6, + "type":"plain", + "lastModified":1541528026, + "createdAt":1541528026, + "labels":null, + "assignedUsers":null, + "attachments":null, + "attachmentCount":null, + "owner":"admin", + "order":999, + "archived":false, + "duedate":null, + "deletedAt":0, + "commentsUnread":0, + "id":10, + "overdue":0 +} +``` + ##### 200 Success ### PUT /board/{boardId}/stacks/{stackId}/cards/{cardId} - Update card details @@ -445,6 +464,27 @@ The board list endpoint supports setting an `If-Modified-Since` header to limit | stackId | Integer | The id of the stack the card belongs to | | cardId | Integer | The id of the card | +#### Request data + +| Parameter | Type | Description | +|-------------|-----------|------------------------------------------------------| +| title | String | The card title | +| 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 | + + +``` +{ + "title": "Test card", + "description": "A card description", + "type": "plain", + "order": 999, + "duedate": null, +} +``` + #### Response ##### 200 Success @@ -473,6 +513,11 @@ The board list endpoint supports setting an `If-Modified-Since` header to limit | stackId | Integer | The id of the stack the card belongs to | | cardId | Integer | The id of the card | +#### Request data + +| Parameter | Type | Description | +| --------- | ------- | --------------------------------------- | +| labelId | Integer | The label id to assign to the card | #### Response ##### 200 Success @@ -487,6 +532,12 @@ The board list endpoint supports setting an `If-Modified-Since` header to limit | stackId | Integer | The id of the stack the card belongs to | | cardId | Integer | The id of the card | +#### Request data + +| Parameter | Type | Description | +| --------- | ------- | --------------------------------------- | +| labelId | Integer | The label id to remove to the card | + #### Response ##### 200 Success @@ -501,6 +552,12 @@ The board list endpoint supports setting an `If-Modified-Since` header to limit | stackId | Integer | The id of the stack the card belongs to | | cardId | Integer | The id of the card | +#### Request data + +| Parameter | Type | Description | +| --------- | ------- | --------------------------------------- | +| userId | String | The user id to assign to the card | + #### Response ##### 200 Success @@ -515,6 +572,12 @@ The board list endpoint supports setting an `If-Modified-Since` header to limit | stackId | Integer | The id of the stack the card belongs to | | cardId | Integer | The id of the card | +#### Request data + +| Parameter | Type | Description | +| --------- | ------- | --------------------------------------- | +| userId | String | The user id to assign to the card | + #### Response ##### 200 Success @@ -529,6 +592,14 @@ The board list endpoint supports setting an `If-Modified-Since` header to limit | stackId | Integer | The id of the stack the card belongs to | | cardId | Integer | The id of the card | +#### Request data + +| Parameter | Type | Description | +| --------- | ------- | ----------------------------------------------------------- | +| order | Integer | The position in the stack where the card should be moved to | +| stackId | Integer | The id of the stack where the card should be moved to | + + #### Response ##### 200 Success @@ -548,6 +619,16 @@ The board list endpoint supports setting an `If-Modified-Since` header to limit ##### 200 Success +```json +{ + "title": "Abgeschlossen", + "color": "31CC7C", + "boardId": "2", + "cardId": null, + "id": 5 +} +``` + ### POST /board/{boardId}/labels - Create a new label #### Request parameters @@ -556,6 +637,15 @@ The board list endpoint supports setting an `If-Modified-Since` header to limit | --------- | ------- | ---------------------------------------- | | boardId | Integer | The id of the board the label belongs to | +#### Request data + +```json +{ + "title": "Finished", + "color": "31CC7C" +} +``` + #### Response ##### 200 Success @@ -569,6 +659,16 @@ The board list endpoint supports setting an `If-Modified-Since` header to limit | boardId | Integer | The id of the board the label belongs to | | labelId | Integer | The id of the label | + +#### Request data + +```json +{ + "title": "Finished", + "color": "31CC7C" +} +``` + #### Response ##### 200 Success @@ -602,6 +702,32 @@ The board list endpoint supports setting an `If-Modified-Since` header to limit ##### 200 Success +```json +[ + { + "cardId": 5, + "type": "deck_file", + "data": "6DADC2C69F4.eml", + "lastModified": 1541529048, + "createdAt": 1541529048, + "createdBy": "admin", + "deletedAt": 0, + "extendedData": { + "filesize": 922258, + "mimetype": "application/octet-stream", + "info": { + "dirname": ".", + "basename": "6DADC2C69F4.eml", + "extension": "eml", + "filename": "6DADC2C69F4" + } + }, + "id": 6 + } +] + +``` + ### GET /board/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{attachmentId} - Get the attachment file #### Request parameters @@ -627,6 +753,15 @@ The board list endpoint supports setting an `If-Modified-Since` header to limit | stackId | Integer | The id of the stack the attachment belongs to | | cardId | Integer | The id of the card the attachment belongs to | +#### Request data + +| Parameter | Type | Description | +| --------- | ------- | --------------------------------------------- | +| type | String | The type of the attachement | +| file | Binary | File data to add as an attachment | + +For now only `deck_file` is supported as an attachment type. + #### Response ##### 200 Success @@ -642,6 +777,15 @@ The board list endpoint supports setting an `If-Modified-Since` header to limit | cardId | Integer | The id of the card the attachment belongs to | | attachmentId | Integer | The id of the attachment | +#### Request data + +| Parameter | Type | Description | +| --------- | ------- | --------------------------------------------- | +| type | String | The type of the attachement | +| file | Binary | File data to add as an attachment | + +For now only `deck_file` is supported as an attachment type. + #### Response ##### 200 Success diff --git a/lib/Controller/AttachmentApiController.php b/lib/Controller/AttachmentApiController.php index 8e82739a0..e2c044e1a 100644 --- a/lib/Controller/AttachmentApiController.php +++ b/lib/Controller/AttachmentApiController.php @@ -25,6 +25,7 @@ namespace OCA\Deck\Controller; use OCP\AppFramework\ApiController; use OCP\AppFramework\Http; use OCP\AppFramework\Http\DataResponse; +use OCP\AppFramework\Http\FileDisplayResponse; use OCP\IRequest; use OCA\Deck\Service\AttachmentService; @@ -56,7 +57,7 @@ class AttachmentApiController extends ApiController { */ public function display() { $attachment = $this->attachmentService->display($this->request->getParam('cardId'), $this->request->getParam('attachmentId')); - return new DataResponse($attachment, HTTP::STATUS_OK); + return $attachment; } /**