Nested Ressource

[nchaulet]

Hi I am currently trying to implement an API using your bundle and I need to have nested ressource like this

/posts/1/images

It's possible to do it ?

[dunglas]

This is not supported out of the box (only top level resources are) but it should be doable using some custom classes for the Image resource type:

• a custom operations with a custom route: https://github.com/dunglas/DunglasApiBundle/blob/master/Resources/doc/operations.md#creating-custom-operations (take a look at how the factory work)
• a custom IriConverter supporting nested resources: https://github.com/dunglas/DunglasApiBundle/blob/master/Api/IriConverter.php#L103-L106

Any feedback (as well as PR to ease doing that) is welcome!

[yecraftsman]

Hi everyone,

Add a simple resource /organizations/{id}/contacts is an obstacle course.

Is there a simpler way that can do that ?
for example be based on the between entities relationship for automatically build nested resources.

[dunglas]

Not for now but as it's a recurrent request, I'll try to make it happens in v2.

[yecraftsman]

Hi @dunglas

Thank you for your reply, how do you think incorporate the nested resources in the V2 ?
I am on a project and I want move forward on the subject.

[akomm]

Some thoughts (not facts) regarding nested resources, please give feedback what you think about it.

First, few things to mention:

Actually a collection and an item are different resources. But for simplicity they are by default bundled inside one class, which defines/describes both collection and item operations, types, etc. If you would ever desire to separate it, you can always create a Resource for collection and for item and define operations for item and collection separate. The API allow us to do so. But it works perfectly well without hacking a lot around and that is good, why make things complicated? Still, for understanding my thoughts, keep this difference in mind. Collection = Resource (identified by IRI), each Item = Resource (identified by IRI). I will have to differentiate between those two things.

The thoughts are based on the idea to be pragmatic and make the solution easier, by removing theoretically correct things, which would maybe never make any sense - stripping them makes the implementation easier. This maybe invites for feedback.

• Nested resources makes only sense, when owned by only one parent resource. For example: comments of an article, e. G. /articles/23/comments. This makes it more convenient, because you don't have to do something like that: /comments/?article=/articles/23.
• Also theoretically a collection can be nested in another collection, because both are resources, but by all creativity I can not imagine any application for such an implementation. You typically will nest a resource inside another item resource.

What if we had a ChildResource base type, beside the Resource type we already have? This could additionally provide its parent Resource.

api.operation_factory could check if the provided resource is a child resource. It could, based on above thoughts, look up for an item operation (get) and generate a child route using the parent routes path and the defined or generated child routes path. This can be made recursive. The route parameters for identifiers of all parent resources can be prefixed, for example by the resource short name, normalized. e. G. for the child route, parents resource short-named by "Product" could become "product_id".

The IriConverter would handle the item IRI generation almost the same way it does now. It would only have to work with a single route. Getting Identifier for all parent resources, prefix them for the route params the same way the factory does.

Note: this are only quick thoughts. For example the prefixing for the route params should be unfinied and optionally configurable, etc.

Also, each operation might have multiple methods allowed. Not quite sure, if there is any problem, if the discovered item operation includes get, but also some other methods, is used by the factory for the child route generation. In cases you want to handle different methods on same path in a single controller (method/invokable). It would not affect this though, its rather a question of "does it make any sense".

[bpolaszek]

👍 +1 for this feature.

I have a Transaction entity that has a ManyToOne relationship with an Affiliate entity.
So I have the following endpoints:
/affiliates
/affiliates/{id}
/transactions
/transactions/{id}

And I want something like that:
/affiliates/{id}/transactions

My temporary solution is to make use of a controller (or an action - I'm using the brilliant DunglasActionBundle) to make this happen.
However, for the moment I cannot extend the /affiliates/{id} route with something external to api_platform, since it would conflict with the resource router.

So, my solution is to temporarily change the URL that I want with something like
/affiliate_exports/{id}/transactions

And here's my action class:

<?php

namespace AppBundle\Action;

use ApiPlatform\Core\JsonLd\EventListener\ResponderViewListener;
use AppBundle\Entity\Affiliate;
use AppBundle\Entity\Transaction;
use BenTools\HelpfulTraits\Symfony\EntityManagerAwareTrait;
use Doctrine\Common\Collections\Criteria;
use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;
use Symfony\Bridge\Doctrine\ManagerRegistry;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpKernel\Exception\BadRequestHttpException;

class TransactionsFeedAction {

    use EntityManagerAwareTrait;

    /**
     * TransactionsFeedAction constructor.
     * @param ManagerRegistry $managerRegistry
     */
    public function __construct(ManagerRegistry $managerRegistry) {
        $this->managerRegistry = $managerRegistry;
    }

    /**
     * @Route("/affiliate_exports/{affiliate}/transactions", name="transactions_export")
     * @param Request   $request
     * @param Affiliate $affiliate
     * @return array
     * @throws \Doctrine\ORM\Query\QueryException
     */
    public function __invoke(Request $request, Affiliate $affiliate) {

        $request->attributes->set('_api_format', ResponderViewListener::FORMAT);
        $request->attributes->set('_resource_class', Transaction::class);
        $request->attributes->set('_collection_operation_name', 'get');

        $criteria     = Criteria::create()  ->  where(Criteria::expr()->eq('affiliate', $affiliate))
                                            ->  andWhere(Criteria::expr()->gte('createdAt', $this->getStartDateFromRequest($request)))
                                            ->  andWhere(Criteria::expr()->lte('createdAt', $this->getEndDateFromRequest($request)));

        $repository   = $this->getRepositoryOf(Transaction::class);
        $qb           = $repository->createQueryBuilder('t')->select('t')->addCriteria($criteria);
        $query        = $qb->getQuery();
        $transactions = $query->getResult();
        return $transactions;
    }

    /**
     * @param Request $request
     * @return \DateTimeImmutable
     */
    private function getStartDateFromRequest(Request $request) {
        $startDate = $request->query->get('startDate', date('Y-m-d'));
        try {
            return (new \DateTimeImmutable($startDate))->modify('midnight');
        }
        catch (\Exception $e) {
            throw new BadRequestHttpException('Invalid startDate input.');
        }
    }

    /**
     * @param Request $request
     * @return \DateTimeImmutable
     */
    private function getEndDateFromRequest(Request $request) {
        $endDate = $request->query->get('endDate', $this->getStartDateFromRequest($request)->format('Y-m-d H:i:s'));
        try {
            return (new \DateTimeImmutable($endDate))->modify('+1 day -1 second');
        }
        catch (\Exception $e) {
            throw new BadRequestHttpException('Invalid endDate input.');
        }
    }

}

A bit tricky, but it works.

[soyuka]

I'm doing this in a DataProvider to keep a separation of concerns. But usually I'm confronted to this only with READ operations, and as we almost always need something that's not a simple join I don't see how this feature would fit into api-platform.

Btw, why can't you simply request /api/transactions?affiliates=X&createdAt[after]=Y&createdAt[before]=Z? with the right filters this should work no?

Btw, why can't you simply request /api/transactions/1?affiliates=X&createdAt[after]=Y&createdAt[before]=Z

Or, you can add the correct serialization group to get your ManyToOne while fetching a transaction :).

[bpolaszek]

Of course I can !

It's just simpler to read, and looks more natural, since a transaction MUST belong to an affiliate :-)

Besides, for business reasons, listing all the transactions is useless. A transaction listing only makes sense when they all belong to the same affiliate.

It's just an example (I just started this application from scratch today for test purposes) but I've been confronted to many use cases where listing all entities doesn't make sense when not grouped to a specific relationship.

The images or the comments of a post, for instance, illustrate this well.

[soyuka]

Yes indeed, but for example requesting a post, and it's comments (I'm using httpie):

http GET localhost/api/post/1

And I'm setting up serialization groups to automagically join comments (in api-platform v2 you can setup groups per resource operation). Because ofc, it's pointless to fetch comments when requesting the post collection. On the other hand, it makes sense (to me) to fetch comments when requesting an item.

[bpolaszek]

I know what you mean, but here are my objections:

• When I request /affiliate/1 I expect to get the affiliate main informations: the transactions are secundary
• I may have a huge number of transactions (thousands)
• When retrieving transactions, date range parameters are mandatory
• I should be able to give the link /affiliate/1/transactions to an affiliate (who doesn't need to know the REST principles) for retrieving his transactions in a specific range
• The affiliate shouldn't have access to /affiliate/1 because perhaps he could see the isAsshole: true property :)

[soyuka]

haha I love the last example.

So, basically you want the localhost/api/transaction?affiliate=X&createdAt[after]=Y&createdAt[before]=Z. collection :).

Indeed, if you wanted the /affiliate/1/transactions you'll have to add a custom operation and at least a DataProvider (controller isn't really needed here).

About mandatory parameters you can already tell to api-platform filters that a parameter is required.

• The affiliate shouldn't have access to /affiliate/1 because perhaps he could see the isAsshole: true property :)
• When I request /affiliate/1 I expect to get the affiliate main informations: the transactions are secundary

To me, this is more related to security (for example acl) where you ensure that a customer won't have those informations, but will in fact only see what he can. It goes for the isAsshole property but also for main informations. Having /affiliate/1 with transactions give you a way to know that those transactions are in fact related to your affiliation. When you use /affiliate/1/transactions you're kind of loosing this piece of information (yes it's obviously related to /affiliate/1), which is really important when talking about linked data (json-ld).

Nevermind, it's an endless debate, there are good and bad points in each of those implementations, and they mostly differ according to your use cases.
I'm still not convince it's better to call nested resources, but I understand your point.