REST API #535

NebriBlackwing · 2018-07-14T02:05:25Z

The big heavy development work is now done and ready for it's first review round.

I'm planning on writing a series of unit tests against the Api Controllers, and after doing the rebase a bunch of unit tests that were passing are no longer. I'll start taking a look at these units tests later this weekend.

When this PR gets merged it will close Issue #83

NebriBlackwing · 2018-07-14T20:20:57Z

@juliushaertl I've managed to reduce the number of errors that were happening with the units tests down to 1. It was pretty simple, phpunit removed setExpectedException and replaced it with a new function. Here's my reference: Roave/BetterReflection#170

The last error is eluding me at the moment, mind giving insights on how to proceed past that error? I'll be starting my own unit tests against the new API real soon :).

juliusknorr · 2018-07-15T10:03:48Z

appinfo/routes.php

+		['name' => 'board_api#undo_delete', 'url' => '/api/v1.0/boards/{boardId}/undo_delete', 'verb' => 'POST'],
+
+		['name' => 'stack_api#index', 'url' => '/api/v1.0/boards/{boardId}/stacks', 'verb' => 'GET'],
+		['name' => 'stack_api#index', 'url' => '/api/v1.0/boards/{boardId}/stacks/{stackId}', 'verb' => 'GET'],


Shouldn't that be handled by stack_api#get

yup! a simple copy/paste oversight!

juliusknorr · 2018-07-15T10:23:02Z

lib/Controller/Helper/ApiHelper.php

+
+class ApiHelper {
+
+	public static function entityHasError($entityId, $entityName, $service) {				


I think we can remove the static keyword, since we will always call this on an object due to dependency injection.

juliusknorr · 2018-07-15T10:24:06Z

lib/Controller/StackApiController.php

+
+		$stack = $this->service->find($this->request->params['stackId']);
+
+		if ($stack == false || $stack == null) {


=== instead of ==

juliusknorr · 2018-07-15T10:24:13Z

lib/Controller/StackApiController.php

+
+		$stack = $this->service->delete($this->request->params['stackId']);		
+
+		if ($stack == false || $stack == null) {


=== instead of ==

juliusknorr · 2018-07-15T10:25:58Z

lib/Controller/Helper/ApiHelper.php

+			return $error;
+		}
+
+		return false;


Probably better to return an empty array then, so we can have proper return type hints once we have PHP 7.0 as a minimum.

juliusknorr · 2018-07-15T10:34:23Z

lib/Controller/CardApiController.php

+			return new DataResponse('card id must be a number', HTTP::STATUS_BAD_REQUEST);
+		}
+
+		$card = $this->cardService->find($this->request->params['cardId']);


Something more general regarding the service classes. They actually throw various exceptions that come from either the permissionService or the db mappers. Sorry those are not correctly documented in the phpDoc comments. So we need to either add a try/catch block here or extend the service methods to return null in case there is no enity found.

Another approach would be to have a middleware for the API that catches the exceptions and returns a 404 for DoesNotExistException for example.

Which would you prefer? I'm usually all for the try { catch } blocks as it makes the code that much more clear / self documenting, typically avoiding exactly this kind of scenario. I did a test for (false || null) just as a starting point.

All the services are able to throw these exceptions?

Yes, that makes sense. Let's go that way. Basically they all throw exceptions based on the mapper, but I can push some commit to add proper annotations later, if that helps.

juliusknorr · 2018-07-15T12:57:45Z

@Nebri I quickly pushed a commit to fix the one failing test.

codecov · 2018-07-15T13:05:16Z

Codecov Report

Merging #535 into master will decrease coverage by 3.65%.
The diff coverage is 61.09%.

@@            Coverage Diff             @@
##           master     #535      +/-   ##
==========================================
- Coverage   79.12%   75.46%   -3.66%     
==========================================
  Files          46       52       +6     
  Lines        1643     1969     +326     
==========================================
+ Hits         1300     1486     +186     
- Misses        343      483     +140

juliusknorr · 2018-07-15T13:09:37Z

@Nebri Any another one to add the exception annotations. At some point it would probably be a good idea to catch the database exceptions in the service classes and throw exceptions that better show what exactly went wrong.

E.g. for the CardServce::update method we currently have:
NoPermissionException which is fine
StatusException if the board or card is archived
MultipleObjectsReturnedException|DoesNotExistException if the query for the card goes wrong: Controllers don't need to know about that, a NotFoundException for the cardId would be the best here I guess.

Would that make sense from your POV?

NebriBlackwing · 2018-07-15T13:28:34Z

MultipleObjectsReturnedException|DoesNotExistException if the query for the card goes wrong: Controllers don't need to know about that, a NotFoundException for the cardId would be the best here I guess.

Yup That makes perfect sense to me! 👍

NebriBlackwing · 2018-07-15T16:20:11Z

@juliushaertl Mind taking a look over my commit: ede2144? Getting a bit lost in the weeds on mocking up a unit test that will cause the permissions to fail, and throw the permission exception. Once I figure that out, I'll be able to make a test to ensure the proper DataResponse is generated.

I commented out the code segment I'm struggling with, and labelled it as a place of dragons ;)

NebriBlackwing · 2018-07-16T09:13:09Z

@juliushaertl

The board service should throw a NoPermissionEyception for this test case. Since we're unit testing there is no need to check if the PermissionService method is called. We can just assume that this is handled correctly.

Is this true for all the exceptions that could be occuring in the rest api? I've taken a look at SharingMiddleware and I've noticed it's taking exceptions and returning out json responses.

if you look at the Board / Stack api controllers I've defined, I'm also trying to build the same json responses using the DataResponse class. Am I essentially creating duplicating code that I don't need to?

The rest api code branch so far is almost at 2,000 lines, and based on our discussions this is seeming to get out of hand. Want to make 100% sure I'm not wasting effort re-inventing the wheel here :).

juliusknorr · 2018-07-16T10:02:35Z

Is this true for all the exceptions that could be occuring in the rest api? I've taken a look at SharingMiddleware and I've noticed it's taking exceptions and returning out json responses.

Yes, at least for the NoPermissionException, which is a StatusException that is catched by the Middleware.

if you look at the Board / Stack api controllers I've defined, I'm also trying to build the same json responses using the DataResponse class. Am I essentially creating duplicating code that I don't need to?

You can get rid of those checks https://github.com/nextcloud/deck/pull/535/files#diff-aa1cba99409af542c6b24c8140e1415bR115

The middleware will automatically return a JSONResponse for any StatusException that is thrown in a controller.

We probably should also move the other checks to the services and just throw a StatusException for those as well, but I need to think about that a bit.

NebriBlackwing · 2018-07-16T10:18:20Z

Alright I'm going to pause work on this branch until we have a solid plan of attack for how to handle these exceptions, as it greatly affects the complexity and location of the relevant unit tests.

NebriBlackwing · 2018-07-17T02:48:27Z

@juliushaertl This is ready for another review round.

juliusknorr · 2018-07-18T19:34:20Z

lib/BadRequestException.php

+namespace OCA\Deck;
+
+use OCP\AppFramework\Http;
+class BadRequestException extends \Exception {


extend from StatusException so we don't need an additional check for that in the Middleware.

juliusknorr · 2018-07-18T19:34:44Z

lib/Middleware/SharingMiddleware.php

@@ -59,7 +60,7 @@ public function __construct(ILogger $logger, IConfig $config) {
 	 * @throws \Exception
 	 */
 	public function afterException($controller, $methodName, \Exception $exception) {
-		if ($exception instanceof StatusException) {
+		if ($exception instanceof StatusException || $exception instanceof BadRequestException) {


Not needed if BadRequestException is a StatusException.

juliusknorr · 2018-07-18T19:37:48Z

lib/Controller/LabelApiController.php

+	 * Create a new label
+	 */
+	public function create($title, $color) {
+		$label = $this->labelService->create($title, $color, $this->request->getParam('boardId'));


We still need some checks as in the other services here as well 😉

juliusknorr · 2018-07-18T19:51:33Z

@Nebri Looks good from the Service/Controller separation now.

Some things we still need endpoints for, or maybe we can adjust the current ones to offer an option for are:

Card: Assign/unassign labels
Card: Assign/unassign users
Card: reorder
Stacks: fetch archived
Attachments

I'd be fine if we obmit the following for the first version of the API:

Board: add/update/delete acl (the first api version should be fine without sharing/updating the permissions)

But it would of course nice to also have those 😉

NebriBlackwing · 2018-07-19T14:11:26Z

Of course, let's do it right! I have no intention of rushing this. I've been taking job interviews this week, next week is looking clear for the moment.

NebriBlackwing · 2018-07-24T18:54:25Z

@juliushaertl I've just written the attachments api. I'm assuming that we also want to go through the services to put in the BadRequestException across the board?

I'd also like to request that we do the acl permissions in a separate issue. I'd like to keep the scope creep in check. Let's fix anything that may still be outstanding here, get it merged, and then build the permissions on top.

let me know what you think.

juliusknorr · 2018-07-24T19:35:50Z

I'm assuming that we also want to go through the services to put in the BadRequestException across the board?

That would be good yes.

I'd also like to request that we do the acl permissions in a separate issue. I'd like to keep the scope creep in check. Let's fix anything that may still be outstanding here, get it merged, and then build the permissions on top.

Sure, we can do this later on. Maybe you can just create an issue for that, so we don't forget about it. That will also make it a bit easier to review then. Better have several small steps there 😉

srbaker · 2018-07-30T13:42:34Z

Heya, thanks for jumping on this. @Nebri Every time I had planned to work on it, something else came up, and I just got stuck. Really glad to see this moving along!

Signed-off-by: Ryan Fletcher <[email protected]>

…tests in BoardApiController Signed-off-by: Ryan Fletcher <[email protected]>

…it tests. Signed-off-by: Ryan Fletcher <[email protected]>

Signed-off-by: Ryan Fletcher <[email protected]>

…odacy complexity rules by a lot. Also moved validation checks into respective services. Signed-off-by: Ryan Fletcher <[email protected]>

Signed-off-by: Ryan Fletcher <[email protected]>

… extending StatusException Signed-off-by: Ryan Fletcher <[email protected]>

Signed-off-by: Ryan Fletcher <[email protected]>

…ntApicontroller. Trying out test driven development. Signed-off-by: Ryan Fletcher <[email protected]>

…dService Signed-off-by: Ryan Fletcher <[email protected]>

Signed-off-by: Ryan Fletcher <[email protected]>

… DefaultBoardService BadRequestException checks. Signed-off-by: Ryan Fletcher <[email protected]>

Signed-off-by: Ryan Fletcher <[email protected]>

Signed-off-by: Julius Härtl <[email protected]>

NebriBlackwing requested a review from juliusknorr July 14, 2018 02:41

juliusknorr added enhancement backend 3. to review labels Jul 14, 2018

juliusknorr added this to the 0.5.0 milestone Jul 14, 2018

juliusknorr changed the title ~~Feature/83/json api~~ REST API Jul 14, 2018

juliusknorr reviewed Jul 15, 2018

View reviewed changes

juliusknorr reviewed Jul 18, 2018

View reviewed changes

Ryan Fletcher and others added 23 commits August 15, 2018 21:15

simple code style changes according to codacy standards.

8cac183

Signed-off-by: Ryan Fletcher <[email protected]>

Moved BadRequestException checks to middleware, removed uneeded unit …

d33dd3e

…tests in BoardApiController Signed-off-by: Ryan Fletcher <[email protected]>

Moved Data Response checks into stack serivice, cleaned up related un…

f2268c7

…it tests. Signed-off-by: Ryan Fletcher <[email protected]>

finished writing StackApiControllerTest.php

f1169b9

Signed-off-by: Ryan Fletcher <[email protected]>

Split Card Update in CardApiController as it was gigantic and broke c…

5bc8a36

…odacy complexity rules by a lot. Also moved validation checks into respective services. Signed-off-by: Ryan Fletcher <[email protected]>

Wrote tests for CardApiControllerTest.php

9c81584

Signed-off-by: Ryan Fletcher <[email protected]>

Wrote initial unit tests for LabelApiControllerTest.php

184cd00

Signed-off-by: Ryan Fletcher <[email protected]>

Code cleanup, removing unused code from older iteration.

507a7fd

Signed-off-by: Ryan Fletcher <[email protected]>

fixed up missing checks from labelService, BadRequestException is now…

72aeb72

… extending StatusException Signed-off-by: Ryan Fletcher <[email protected]>

Implemented additional CardApiController endpoints

3e965d0

Signed-off-by: Ryan Fletcher <[email protected]>

Added additional endpoints for cards / stacks

172a80f

Signed-off-by: Ryan Fletcher <[email protected]>

Wrote unit tests for AttachmentApiController and stubbed out Attachme…

e88c9a7

…ntApicontroller. Trying out test driven development. Signed-off-by: Ryan Fletcher <[email protected]>

wrote attachment api controller, fixed bug caught by unit test in Car…

37a2858

…dService Signed-off-by: Ryan Fletcher <[email protected]>

Added in BadRequestException tests into AttachmentService.php

7930fec

Signed-off-by: Ryan Fletcher <[email protected]>

Added BadRequestException checks into BoardService.php

e857145

Signed-off-by: Ryan Fletcher <[email protected]>

Added in BadRequestException checks in CardService.php

6f5c0a2

Signed-off-by: Ryan Fletcher <[email protected]>

Added BadRequestException checks in DefaultBoardService. Fixed bug in…

aba7d02

… DefaultBoardService BadRequestException checks. Signed-off-by: Ryan Fletcher <[email protected]>

added missing BadRequestException checks to StackService.php

4391bf4

Signed-off-by: Ryan Fletcher <[email protected]>

Catch DoesNotExistException to return proper API repsonses

47a7e76

Signed-off-by: Julius Härtl <[email protected]>

Fix comparison

81d3332

Signed-off-by: Julius Härtl <[email protected]>

Mapper can be null if provided id is a board id

0c9b1f5

Signed-off-by: Julius Härtl <[email protected]>

Fix imports

babfcbd

Signed-off-by: Julius Härtl <[email protected]>

Fix controller deleted at parameter

5639bd1

Signed-off-by: Julius Härtl <[email protected]>

juliusknorr force-pushed the feature/83/json-api branch from 12b6b7e to 5639bd1 Compare August 15, 2018 19:15

juliusknorr merged commit f040df7 into master Aug 15, 2018

juliusknorr deleted the feature/83/json-api branch August 15, 2018 19:21

juliusknorr mentioned this pull request Aug 15, 2018

API documentation #588

Closed

poVoq mentioned this pull request Aug 18, 2018

Support Nextcloud Deck Rest API? kuehnelbs/node-red-contrib-nextcloud#6

Open

NebriBlackwing mentioned this pull request Aug 21, 2018

BoardService returns 403 instead of not found #531

Closed

juliusknorr mentioned this pull request Oct 8, 2018

v0.5.0-beta1 #638

Merged

33 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

REST API #535

REST API #535

NebriBlackwing commented Jul 14, 2018

NebriBlackwing commented Jul 14, 2018

juliusknorr Jul 15, 2018

NebriBlackwing Jul 15, 2018

juliusknorr Jul 15, 2018

juliusknorr Jul 15, 2018

juliusknorr Jul 15, 2018

juliusknorr Jul 15, 2018

juliusknorr Jul 15, 2018

NebriBlackwing Jul 15, 2018

juliusknorr Jul 15, 2018 •

edited

Loading

juliusknorr commented Jul 15, 2018

codecov bot commented Jul 15, 2018 •

edited

Loading

juliusknorr commented Jul 15, 2018

NebriBlackwing commented Jul 15, 2018

NebriBlackwing commented Jul 15, 2018 •

edited

Loading

NebriBlackwing commented Jul 16, 2018 •

edited

Loading

juliusknorr commented Jul 16, 2018 •

edited

Loading

NebriBlackwing commented Jul 16, 2018

NebriBlackwing commented Jul 17, 2018

juliusknorr Jul 18, 2018

juliusknorr Jul 18, 2018

juliusknorr Jul 18, 2018

juliusknorr commented Jul 18, 2018

NebriBlackwing commented Jul 19, 2018

NebriBlackwing commented Jul 24, 2018

juliusknorr commented Jul 24, 2018

srbaker commented Jul 30, 2018


		class ApiHelper {

		public static function entityHasError($entityId, $entityName, $service) {


		$stack = $this->service->find($this->request->params['stackId']);

		if ($stack == false \|\| $stack == null) {


		$stack = $this->service->delete($this->request->params['stackId']);

		if ($stack == false \|\| $stack == null) {

REST API #535

REST API #535

Conversation

NebriBlackwing commented Jul 14, 2018

NebriBlackwing commented Jul 14, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

juliusknorr Jul 15, 2018 • edited Loading

Choose a reason for hiding this comment

juliusknorr commented Jul 15, 2018

codecov bot commented Jul 15, 2018 • edited Loading

Codecov Report

juliusknorr commented Jul 15, 2018

NebriBlackwing commented Jul 15, 2018

NebriBlackwing commented Jul 15, 2018 • edited Loading

NebriBlackwing commented Jul 16, 2018 • edited Loading

juliusknorr commented Jul 16, 2018 • edited Loading

NebriBlackwing commented Jul 16, 2018

NebriBlackwing commented Jul 17, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

juliusknorr commented Jul 18, 2018

NebriBlackwing commented Jul 19, 2018

NebriBlackwing commented Jul 24, 2018

juliusknorr commented Jul 24, 2018

srbaker commented Jul 30, 2018

juliusknorr Jul 15, 2018 •

edited

Loading

codecov bot commented Jul 15, 2018 •

edited

Loading

NebriBlackwing commented Jul 15, 2018 •

edited

Loading

NebriBlackwing commented Jul 16, 2018 •

edited

Loading

juliusknorr commented Jul 16, 2018 •

edited

Loading