Next ZfrRest

[bakura10]

Hi,

I'd like to share some thoughts about the future of ZfrRest. After some months of usage, I think I can come with some conclusions:

• The idea of using router to traverse routes was a good idea
• The handler idea for handling verbs was very nice

However, I think that the automatic traversing of associations (aka auto discovery) was a bad idea. While it reduces config, it makes it very hard to do custom cases (for instance, you cannot do "projects/1/members" if projects does not have association to "members", which forces you to manually create a route for that, hence making the config really confusing). Also, it can leads to inefficient code when traversing paths like /invoices/5/line-items/7 as it needs to do db calls than needed.

The problem is that ZF2 router is sooooo verbose that any other solution is even worse. So those ideas would be based on syntax that would look like Dash.

Now, you would simply define all the routes explicitly, removing the need to force creating associations just for the sake of making them discoverable in ZfrRest:

'routes' => [
        'invoices' => [
            '/invoices', InvoiceListController::class, 'children' => [
                'invoice' => ['/:invoice_id', InvoiceController::class, 'children' => [
                    'line-items' => ['/line-items', InvoiceLineItemListController::class, 'children' => [
                        'line-item' => ['/:line_item_id', InvoiceLineItemController::class]
                    ]]
                ]
            ]
        ],

        'line-items' => [
            '/line-items', LineItemListController::class
        ]
    ];

As you can see, all the routes are explicitly defined, allowing you to map specific logic depending on whether you are accessing the resource from a parent resource or not. This will use standard router to dispatch to the right controller. This also greatly simplify links as all the endpoints are clearly defined.

Now, instead of the resource being automatically fetched, you will have more power about how to resolve the resource. The REST controller interface will look like this:

interface RestController
{
    public function createResource(array $params);              
    public function resolveResource(array $params);
        public function selectHydrator($method, $params);
        public function selectInputFilter($method, $params);
}

The createResource will be called for verbs like POST, while resolveResource will be called for methods like GET, DELETE or PUT. $params array will always contain all the identifiers matched, so if we matched /invoices/1/line-items/5, we will hit the "InvoiceLineItemController":

class InvoiceLineItemController implements RestController
{
    public function resolveResource(array $params)
    {
        return $this->service->getInvoiceLineItemForInvoice($params['invoice_id'], $params['line_id]);
    }
}

The thing is that, obviously, this is still boilerplate code, while we can often assume defaults on this. To that extent, when defining route, you will be able to define a resource:

'routes' => [
        'invoices' => [
            '/invoices', InvoiceListController::class, 'children' => [
                'invoice' => ['/:invoice_id', InvoiceController::class, 'options' => [
                                    'resource' => Invoice::class
                ]
            ]
        ]
    ];

When we do this, the object repository for "Invoice" will be automatically injected into the controller constructor, and the "resolveResource" will be able to do some work based on conventions. For instance, because the route is called "invoice", it will assume that id is in route parameter "invoice_id", and will match it and do a find. (obviously, ZF3 SM will need some adjustments so we can set a factory for each controller).

In overall, I want to make things more explicit and simpler to understand, while still being able to have some automatisms based on conventions (after using EmberJS a lot, I actually appreciate this a lot). Unfortunately, ZF2 router and SM suffers from some limitations that make it hard to do right now.

For those who are also using ZfrRest in production, was do you think about it?

ping @Ocramius @danizord @Thinkscape

[danizord]

I like the idea in overall.

The biggest problem of ZfrRest for me today is that ZfrRest forces REST resources to always represent Doctrine entities, and I often want to expose some resources that are not Doctrine entities (e.g the Like problem of #158). So, I'm :+1: for the createResource() and resolveResource() as they'll bring more flexibility for developers to expose non-Doctrine resources.

I'm starting another project with ZfrRest today and hopefully I'll have time to contribute with those ideas ;)

[gabrielsch]

I also really like this approach.

My problem was the same of @danizord, I also think ZfrRest should allow non-doctrine entities as resources.

I have some ideas too, probably I'll give my two cents with some PRs.

[bakura10]

Nice to see you like the idea. As I said, ZF2 router is so verbose that it makes this solution not really nice. I'll actually try to play directly with Dash, and eventually see if this can lead to improvements to Dash as well.

@gabrielsch > Exact, I'd like to be able to support non-entities, as well as having a unified way of handling REST verbs AND actions.

[bakura10]

I have given more thoughts to that. What I definitely want is reducing boilerplate code, and I'll indeed need to work in the next months on some other refactored component.

I know @Ocramius hate that, but I definitely want to achieve some compilable annotations stuff. For instance, how cool would it be to do that:

/**
 * @Route(name="users", "path"="/users/:id", type="RestRoute::class")
 */
class UserController extends RestController
{
        /**
         * @Inject
         */
        public function __construct(UserService $userService)
        {
            $this->userService = $userService;
        }

    /**
     * @REST(hydrator="UserGetHydrator")
     */
    public function get(User $user)
    {
    }

    /**
     * @REST(inputFilter="PostInputFilter", validationGroup="post", hydrator="PostHydrator")
         */
    public function post(User $user)
    {

    }
}

[ojhaujjwal]

@bakura10 That looks pretty cool!

[Thinkscape]

if projects does not have association to "members", which forces you to manually create a route for that,

Which is broken btw. :-)

I'd actually want to have automagical solution for resolving that. I do not want to create a resource-sub-resource-sub-resource controller every time. I have well-defined relations and I'd like to fetch them at will.

I don't have much problem with zf2 router, esp. that you can create "flat" routes without having children of children. As long as it's formed correctly and defined first, it'll match correctly.

That said, I kinda like the explicitness of defining the route tree while associating it with controllers, although I currently use just a handful of controllers that support multiple entities at once. Everything else is handled by a factory + annotations, which I find very useful and time saving. Short setup time was my primary concern when choosing zfr-rest :-)