Clear Support for Virtual Resources

[PeterCat12]

Creating "virtual" resources for an API is a common need and I'm struggling creating one using this package. Any thoughts or workarounds on this? Is seems any schema NEEDS an eloquent model which seems very limiting in some very valid use cases.

Thanks!

[lindyhopchris]

Yeah this will be supported, I just haven't got to it yet. It's definitely needed because the previous cloudcreativity/laravel-json-api supported non-Eloquent resources.

The package has been built to work with non-Eloquent resources, I just haven't added tests (that will help me work out how to implement it).

For the moment, if you're writing a schema that isn't for an Eloquent model, extend this schema instead of the Eloquent schema:
https://github.com/laravel-json-api/core/blob/develop/src/Core/Schema/Schema.php

You'd probably need to use the Eloquent fields for the moment, even though they aren't for an Eloquent model. You'll probably have to write a Resource class as well, instead of letting the schema serialize your non-Eloquent model.

[PeterCat12]

Thanks so much for the quick reply.

And GREAT WORK on this btw. Really solid stuff. I'm about to do some greenfield development and I'm quite excited to use this package.

[lindyhopchris]

@PeterCat12 thanks so much for the feedback! it's taken a lot of work, so glad to hear you find it useful!

BTW are you able to share a description of what your virtual resource is and how it needs to work? would be useful for when I start working on non-Eloquent resources

[PeterCat12]

I don't have have a specific need yet but the most obvious type of entity where I would not have an explicit Eloquent model tied directly to my route is a Reports type of endpoint that pulls in a variety of data from different eloquent models (any source, such as a 3rd party API, for that matter)

Typically I'd expect to be able to do a GET request with an arbitrary UUID in the route (for example: GET api/v1/reports/69689a42-631a-45ae-bb73-ebaa8e589602) supplied by the client. My response ID would then match the one supplied by the client.

{
"data": {"type": "reports: "id": "69689a42-631a-45ae-bb73-ebaa8e589602", ... }
}

Also with this package expecting an underlying eloquent model for a schema it feels a bit like the API contract is dictating the data layer which feels wrong to me.

So far I've tried to write an implementation where I'm overwriting the base schema class and the normal repository class but I think I goofed! I can return a "virtual resource" okay but I can't set the ID via the id in the route thanks to some code in the JsonApiResource class:

    /**
     * Get the resource's id.
     *
     * @return string
     */
    public function id(): string
    {
        if ($key = $this->schema->idKeyName()) {
            return (string) $this->resource->{$key};  // I need to pull the id from the route URL here. 
        }

        if ($this->resource instanceof UrlRoutable) {
            return (string) $this->resource->getRouteKey();
        }

        throw new LogicException('Resource is not URL routable: you must implement the id method yourself.');
    }

Still understanding the package. I'll try writing my own JsonApiResource class. Thanks.

[lindyhopchris]

Yeah so the schema from the core package does not expect an Eloquent model, so that's why that one should be used instead. I also need to extract the JsonApiResource class to an interface - so that you can just directly implement that interface if needed without having to worry about using the existing JsonApiResource class.

It will definitely be possible to do a non-Eloquent resource as I've written everything with that in mind as I use non-Eloquent resources too. It just needs putting together - which will happen during either the alpha or beta releases as I won't tag 1.0 proper without it.

[PeterCat12]

Managed to support a non-eloquent resource using the JsonApiResource class in tandem with writing my own "virtualRepository" and "VirtualSchema" class. My implementation does feel a bit wrong to me though, especially with your comments here.

Is there already an appropriate place where I can hook into and specify which JsonApiResource class to instantiate/use If I do try writing my own?

[lindyhopchris]

So you can manually register the mapping of a schema class to a resource class here:
https://github.com/laravel-json-api/core/blob/develop/src/Core/Resources/ResourceResolver.php#L46-L49

To be honest, I'm getting very close to needing a non-Eloquent resource in the APIs I'm working on at the moment. So if you give me a week or two there will probably be a documented and tested solution as I'll be forced to write it for what I'm working on!

[PeterCat12]

I can definitely wait that long :)
Thank you very much, sir!!!

[X-Coder264]

@lindyhopchris I've had the need for a couple of non Eloquent resources, and most of them were just stuff like reporting for some data with custom queries etc. so it was just an index action which just returned new DataResponse($reports);.

The base non-Eloquent schema \LaravelJsonApi\Core\Schema\Schema makes you implement the repository method (because that's the requirement of the \LaravelJsonApi\Contracts\Schema\Schema interface). I've never had any need for the repository so I had to create dummy repositories which don't do anything for all my virtual resources. I think it'd be best if the base schema interface does not contain that method which can be moved in a "repository aware schema" interface (or something like that) which can be used in the parts of the package which actually need the repository in order to work, so that users are not forced to implement stuff they don't need as in my use case.

Also it's really weird to be using fields (like \LaravelJsonApi\Eloquent\Fields\Str) from the Eloquent namespace for non-Eloquent resources. If those fields do not require Eloquent it'd be best to move them to another non Eloquent namespace (before the beta release as I guess the beta releases won't make any additional breaking changes?).

Also as an additional question, my current non Eloquent resources look like this

final class MonthlyReport
{
    public string $id;
    public CarbonImmutable $date;
    public array $reportData;

    public function __construct(CarbonImmutable $date, array $reportData)
    {
        $this->id = Str::uuid()->toString();
        $this->date = $date;
        $this->reportData = $reportData;
    }
}

I'd really like to make them immutable (so that they have only getters, instead of leaving the properties public). I didn't have a lot of time to check but is there some way of telling in the schema how the data can be fetched from the object?

Something like

DateTime::make('date')->readOnly()->fetchUsing(function (MonthlyReport $monthlyReport) {
       return $monthlyReport->getDate();
})->serializeUsing(static function (CarbonImmutable $date): string {
      return $date->format('Y-m');
}),

[lindyhopchris]

@X-Coder264 I've actually implement a non-Eloquent resource capability, which I'm currently writing documentation for. It works by installing this package: https://github.com/laravel-json-api/non-eloquent

I'm about a third of the way through the documentation. I'll post a link to the docs here once I've finished them.

[X-Coder264]

@lindyhopchris Nice. I'll check that out once the documentation is done, but as far as I can see from the tests the repository thingy is still (always) required, right?

[lindyhopchris]

@X-Coder264 yeah good point, I'll make the repository optional now.

[lindyhopchris]

Documentation for non-Eloquent resources is here:
https://github.com/laravel-json-api/docs/blob/develop/1.0/digging-deeper/non-eloquent.md

I'm just about to tag all the packages as 1.0.0-beta.1

[lindyhopchris]

Closing this as this has now been tagged as 1.0.0-beta.1. If you encounter any problems when using this new feature, just create a new issue with details of the problem.