Chaining nested endpoint?

[bnzo]

Considering an API with nested enpoints like /movies/12345/actors/12343

$api = new API('my-api-token');
$movieId = 12345;

Instead​ of

$response = $api->movies()->getActors($movieId);

Will be great to do:

$response = $api->movie($movieId)->actors();

[Sammyjo20]

That's a cool idea! As you say it's not a feature in Saloon yet, but you could make custom methods that instantiate your own request collections/service classes

[juse-less]

I have to say - I love this idea.
Now I have to refactor all my integrations APIs again, using this approach. 😄
It'd simplify and encapsulate logic so much for me, in a system I'm developing.

How have I not thought of this before?!

---

@Sammyjo20 Considering request collections are called as methods on the connector, would it be possible to forward any arguments that method receives, as constructor arguments to the request collection?
I know the current request collection class takes the SaloonConnector (which I believe it should, in order to construct the object), but just thinking out loud.
Off the top of my head would be to just overwrite __call() of the connector and quickly throw in the forwarding there.
I'm open for ideas on how to solve that forwarding correctly, as having to define the connector as part of the constructor arguments can be 'intrusive' from a DX perspective.

Forwarding the arguments could at least open it up for us to manually reuse/forward those parameters in the request collection.

Something like this.

$movieApi = new MovieApi;
$movieActors = $movieApi->movie(42)->getActors();
// Some logic ...
$movieApi->movie(42)->updateActors(UpdateActorsData::from([
    // Some payload for updating. Given plural, it should be a collection of actors, though.
]));

class MovieRequestCollection extends RequestCollection
{
    public function __construct(
        protected readonly int $movieId,
    ) {}

    public function getActors(): SaloonResponse
    {
        return GetMovieActorsRequest::make(
            $this->movieId,
        )->send();
    }

    public function updateActors(
        UpdateActorsData $payload,
    ): SaloonResponse {
        return UpdateMovieActorsRequest::make(
            $this->movieId,
            $payload,
        )->send();
    }
}

class GetMovieActorsRequest extends SaloonRequest
{
    protected string|null $method = Saloon::GET;

    public function __construct(
        protected readonly int $movieId,
    ) {}

    public function defineEndpoint(): string
    {
        return "/movies/{$this->movieId}/actors";
    }
}

class UpdateMovieActorsRequest extends SaloonRequest
{
    protected string|null $method = Saloon::PATCH;

    public function __construct(
        protected readonly int $movieId,
        protected readonly UpdateActorsData $payload,
    ) {}

    public function defineEndpoint(): string
    {
        return "/movies/{$this->movieId}/actors";
    }

    // ... methods to define request payload and query params
}

I guess another approach would be to add certain config properties to the request collection, like defineEndpoint(), to collectively define properties for requests that could be merged with the request data (where request data still takes precedence).
Although, this would be problematic if requests are instantiated from the collection (as my example above), as opposed to the connector (like the documentation does).

[bnzo]

@juse-less using the RequestCollection is very interesting! It might be simpler to create a new Request Collection class like NestedRequestCollection to handle one or maybe multiple arguments without affecting the existing RequestCollection?

I was thinking about another way to deal with those kind of nested requests. Having a directory structure reflecting the nested endpoints: By adding some configurations to the Connector and/or RequestCollection, calls could be done by reflexion. But I guess harder to make it generic.

@Sammyjo20 I guess we should wait for V2 before considering one or the other. In awaiting, custom methods calling the right requests is working great.

[juse-less]

using the RequestCollection is very interesting! It might be simpler to create a new Request Collection class like NestedRequestCollection to handle one or maybe multiple arguments without affecting the existing RequestCollection?

This is what I had in mind.

---

Saloon v2 drops RequestCollections entirely for simplicity.
They are simple classes we can create separately, which gives us more possibilities without directly relying on Saloon and its implementation details.
Then we can add them to our Connector, either by real methods directly, or implement our own, simple, __call() and/or __callStatic() forwarder(s) like Saloon v1 does.
As simple as the solution is in v1, it still reduces 'complexity' in Saloon, and Sam doesn't have to maintain those.

---

I've currently replaced my RequestCollections with a repository pattern in v2, but will re-do RequestCollections for nested paths like 'singular' resources.
I.e., /movie/:id/.
It's working very well for me so far, but still missing some pieces like 'automagic' paging capabilities, and what not.

[juse-less]

I had the intention of trying to make (and PR) first-party support for 'single resource request collections'.
But I'm not gonna have time before v2.
Because it's fairly easy to implement the pattern, and v2 in itself is a fairly big overhaul, maybe it'd be better to wait to v3 anyway to see how useful it'd be to add it.

Nonetheless, I replicated how I'm currently dealing with it in v2, in an internal system which has a lot of API integrations.
I'd like to adjust naming, but it's less of a concern right now.
Hopefully it helps someone. 🙂

Code samples:

Example Request (GetUserRequest)

/**
 * @method  static  static  make(int $id)
 */
class GetUserRequest extends Request
{
    protected Method $method = Method::GET;

    protected string|null $response = GetUserResponse::class;

    public function __construct(
        public readonly int $id,
    ) {}

    public function resolveEndpoint(): string
    {
        return "/users/{$this->id}";
    }
}

Resource

abstract class Resource
{
    public function __construct(
        protected readonly MyApiConnector $myApi,
    ) {}
}

ResourceRepository

abstract class ResourceRepository
{
    public function __construct(
        protected readonly MyApiConnector $myApi,
    ) {}
}

User

class User extends Resource
{
    public function __construct(
        MyApiConnector $myApi,
        protected readonly int $id,
    ) {
        parent::__construct($myApi);
    }

    public function get(): PromiseInterface
    {
        return $this->myApi->sendAsync(GetUserRequest::make(
            $this->id,
        ));
    }

    public function update(UpdateUserRequestData $data): PromiseInterface
    {
        return $this->myApi->sendAsync(UpdateUserRequest::make(
            $this->id,
            $data,
        ));
    }

    // Archive, Unarchive, ...

    public function delete(): PromiseInterface
    {
        return $this->myApi->sendAsync(DeleteUserRequest::make(
            $this->id,
        ));
    }
}

UserRepository

class UserRepository extends ResourceRepository
{
    // total(), pages() - Both call get(),
    //   then just returns the total entries and total pages properties from the response.
    // paginate()

    public function get(): PromiseInterface
    {
        return $this->myApi->sendAsync(GetUsersRequest::make());
    }

    public function user(int $id): UserContract
    {
        return new User($this->myApi, $id);
    }

    public function create(CreateUserRequestData $data): PromiseInterface
    {
        return $this->myApi->sendAsync(CreateUserRequest::make(
            $data,
        ));
    }
}

Example Usage

$connector = new MyApiConnector;
$users = new UserRepository($connector);

$firstUser = $connector->send(new GetUserRequest(1));
$firstUser = $connector->sendAsync(new GetUserRequest(1))->wait();
$firstUser = $users->user(1)->get()->wait();

$connector->send(new ArchiveUserRequest(1));
$connector->sendAsync(new ArchiveUserRequest(1))->wait();
$users->user(1)->archive()->wait();

// Simplified example function - while each page is retrieved concurrently,
//   each archive request will be sent synchronously - pooling should be used.
$archiveUser = function (GetUsersResponse $response) use ($users): void {
    // Each $user is a UserData DTO (not included in examples).
    foreach ($response->users() as $user) {
        $users->user($user->id)->archive();
    }
};


// Archive all users.
$users
    ->paginate()
    ->pool()
    ->withResponse($archiveUser)
    ->send()
    ->wait();

// Note here - because we *don't* pool the paginator/'request',
//   they are synchronous, and we don't need to await any Promises.
foreach ($users->paginate() as $userResponse) {
    //
}

$users->create(new CreateUserData([
    //
]));

$totalUsers = $users->total();
$totalUserPages = $users->pages();

As seen in the example request, the request itself is still the same, regardless of how you use it.
But I've wrapped it in the User Resource for syntactic sugar.
The Resource will simply forward the ID to the request, along with any parameters to the respective method.

I still 'need' to pass around the Connector, which I'm not fond of (because it's mixed with the ID for the Resource, for instance).
I could obviously create a resolveConnector() method on each class, but still - passing around the same connector can still have benefits (think of Guzzles feature to keep cURL open, for instance).

[Sammyjo20]

We are currently working on a PoC for this very feature, head over to #176 if you want to see what we're doing.