It would be nice to get an update with support for Laravel 5.3. Looks like the service provider needs to have it's dependency injection removed from the method signature.

https://laravel.com/docs/5.3/upgrade

We're currently using v0.2, so if an update could be issued to this version, that would be great.

Plan for Version 2

We are starting to turn our attention to version 2 of this package. This issue describes the thinking and invites any comments/suggestions about the approach. We're aware a lot of people are using this package, so we want to get this right.

Background

When we first wrote this Laravel package, it was based on a framework-agnostic implementation because we weren't just using it in a Laravel application. One of the best decisions of the 1.0.0-alpha/beta series was to move the code into this package and develop it as a solely-Laravel package.

During the 1.0 development we started making it feel more like a Laravel package, however there was a limit to how much we could do that without introducing more breaking changes than we were comfortable with.

The other bit of background is that we use the neomerx/json-api package, predominantly for the encoding. That package has a great attention on making encoding performant, so we still want to use it. However, we are not entirely confident that decisions made on that package fit with our overall approach and unfortunately recent changes to that package make extending some of the internals complex.

Additionally, exposing the neomerx interfaces to the Laravel developer makes this package feel less intuitively like a Laravel package - as there's more code to wrap your head around.

Aims

Based on this background, there are two main things we want 2.0 to achieve:

1. Make the use of this package align closely with existing Laravel approaches (wherever possible); and
2. Hide the use of the neomerx package so it becomes an internal implementation detail, rather than something the developer needs to know about.

Laravel Alignment

Currently we have:

- App
    - Http
        - Controllers
            - Api
                - PostsController (optional)
    - JsonApi
        - Posts
            - Adapter
            - Schema
            - Validators
            - Authorizer (optional)
            - ContentNegotiator (optional)

This will still work on 2.0, requiring only minor interface changes and PHP 7 type-hinting to upgrade. Any code relating to the implementation will be marked as deprecated and removed in 3.0.

Our new style for 2.0 will be this:

- App
    - Http
        - Controllers
            - Api
                - PostController (optional)
        - Resources
            - JsonApi
                - PostAdapter
                - PostResource
                - PostCollection (optional)
        - Requests
            - JsonApi
                - PostRequest
                - PostQuery

The reason for the JsonApi namespaces is to prevent collisions with existing classes, e.g an Eloquent PostResource, or an existing PostRequest form request. It also makes it entirely clear which classes are to do with your JSON-API implementation.

There will be an option to sub-namespace things if you have multiple JSON APIs. E.g. if we have a v1 and v2 API, the resources will be JsonApi\V1\PostResource, JsonApi\V2\PostResource etc.

This means the following differences from the current implementation:

• Schema is replaced by PostResource, which will have a similar style to Eloquent resources. Similar is intentionally used, because the Eloquent approach will not fully work for JSON API, and it has some aspects that would undermine the performance of the JSON API encoder. Resource classes will implement Responsable and JsonSerialize so that they can be used in other contexts as required.
• Validators is split into PostRequest for validating request JSON content and PostQuery to validate the query parameters for a response that will contain posts resources.
• Authorizers cease to exist and use standard Laravel authorization via middleware, form request authorize methods, controller middleware and controller helpers.
• ContentNegotiators are removed but the use-case is fully supported (and documented). Different media-types will be easier to wire in as there will be a specific PostRequest and PostQuery on which validation can be customised or skipped.
• Adapters will return either the resource class, or the resource collection class, or null. These will allow the adapter to provide meta and links as needed.
• Standard Laravel route bindings will be used.
• The default controller will be composed using traits, allowing a developer to create their own custom controllers if they want. We will offload the running of the HTTP handling logic into a Server class, so it's easier to call our default handling of JSON API requests from within a custom controller if needed.
• Controller and adapter hooks will be replaced with standard Laravel events. For resource update events, we will provide data about the before and after state, allowing listeners to decide to do something if a resource field has changed.
• We will enable auto-generation of API docs by inspecting defined routes and the request/query classes. We will show example resources by serializing models created via Eloquent factories. This means the docs output will need to be created in development, and can then be committed to version control.

As an example, our new default controller would look like this:

<?php

namespace CloudCreatvity\LaravelJsonApi\Http\Controllers;

use CloudCreativity\LaravelJsonApi\Http\Actions;

class ResourceController
{

    use Actions\Index;
    use Actions\Store;
    use Actions\Show;
    use Actions\Update;
    use Actions\Destroy;
    use Actions\Related\Show;
    use Actions\Relationships\Show;
    use Actions\Relationships\Replace;
    use Actions\Relationships\Add;
    use Actions\Relationships\Remove;
}

The action names here match Laravel's default names for resource controllers - except for relationships, as they are a JSON API concept.

This means that if the developer wanted to write their own controller, changing the method signatures of some of the actions, they could compose their own controller using our traits - but omit the ones they want to change. E.g.

<?php

namespace App\Http\Controllers\Api;

use App\Http\Controllers\Controller;
use App\Http\Resources\JsonApi\PostRequest;
use App\Http\Resources\JsonApi\PostQuery;
use CloudCreativity\LaravelJsonApi\Http\Actions;
use CloudCreativity\LaravelJsonApi\Facades\JsonApi;
use Illuminate\Contracts\Support\Responsable;

class PostController extends Controller
{

    // default actions, e.g.
    use Actions\Index;

    public function store(\Illuminate\Http\Request $request): Responsable
    {
        if ($something) {
            // return something custom.
        }

       // use our standard implementation via the `server()` helper.
       // lazily resolving the request/query classes means JSON API validation only happens now.
       return JsonApi::server()->store(
            app(PostRequest::class),
            app(PostQuery::class)
        );
    }
}

Outside of HTTP requests, you can query your resources using a fluent JSON API query syntax. This effectively allows you to run the logic within your adapters in a style familiar to a Laravel Query Builder (but using JSON API terms, such as include). Say we wanted to get a PostResource from a post id:

$resource = JsonApi::resources()->posts()->include('comments', 'author')->find($postId);

return \json_encode($resource);

Neomerx Package

We are currently using v1 of the neomerx package, but it is currently on v3 - which contains a lot of performance improvements. We therefore desperately need to upgrade.

However, as the current implementation involves developers extending or type-hinting classes/interfaces from the neomerx package, this change will be extremely breaking.

As we plan to change our use of the neomerx package to an internal implementation detail, 2.0 of our package will set the neomerx Composer constraint to ^1.0.3|^3.0. We will detect the version installed, caching the answer in config for performance reasons, and adjust the implementation internally to use either.

Developers will therefore be able to upgrade to 2.0 without changing their existing Schemas etc. And can then upgrade to neomerx v3 once they have converted to the new PostResource pattern described above.

How Can You Help?

Provide comments on this approach and highlight potential problems, so that we know whether we're on the right track!

We think that with these changes, this package will be one of the best options out there for building standard-compliant APIs in Laravel. So we could really do with a great website with docs that follow the Laravel docs sub-headings (i.e. so that they are instantly familiar to Laravel developers). If you're able to help out with a public website, let me know.

Hi,

I was trying to save three belongsTo relationships, but for some reason only the first one would go through; While investing it, I dd'ed here https://github.com/cloudcreativity/laravel-json-api/blob/develop/src/Eloquent/AbstractAdapter.php#L370 and saw that it had fetched the relationship before saving, what's the idea behind this?

Eg. when trying to save a client_id on a user, this is the $record being passed to persist:

....{"client_id":1,"client":{"id":1,"currency":"EUR","name":"client-name"}}.

It seems like a redundant fetch from the database?

I also finally found my issue with only some of the relationships being saved, here: https://github.com/cloudcreativity/laravel-json-api/blob/develop/src/Adapter/AbstractResourceAdapter.php#L205

What's the idea behind Camelizing the method-name, when Laravel famously uses snake-case for relationships?

The package is absolutely wonderful, but I'll see if I can get a PR in with some documentation.

Cheers

Hello all,

My first problem was that I wanted my model Temple had the resource type worship:temple instead of temples or temple. I could finally fix it with some Resolver classes, but I think that should be a lot easier.

My second problem I could not solve yet. Now, my Temple class is linked to worship:temple, but I also forced to browse to /worship/v1/worship:temple/ instead of /worship/v1/temples/.

How can I fix this?

Thanks in advance

Now that neomerx/json-api is at 1.0 we want to get this library to 1.0 as soon as possible - to give people confidence that the API is stable.

The recent routing refactor and reducing the number of units per resource type (currently on develop - will be released as 0.8) puts in a lot of pre-1.0 changes that we wanted to do to simplify the package.

Required 1.0 Features

• [x] Full support for filtering, paging etc for relationship endpoints - including test helpers. See #22, #23, #27, #77
• [x] Support with when retrieving single records. See #62
• [x] Hydrator simplification. See #69
• [x] Hydrate Eloquent polymorphic relationships. See #35
• [x] Generic authorizer that hands off to Laravel policies. See #45
• [x] Refactor JsonApiController so that it has the majority of the workflow that currently exists within EloquentController. Extend the Eloquent controller from this new controller.
• [x] Add a broadcast helper trait. See #36
• [x] Add a blade template helper to encode JSON API data into a HTML page. See #36
• [x] Convert tests to Laravel 5.4 style - i.e. remove dependency on laravel/browser-kit-testing.
• [x] Drop support for Laravel 5.3 and ensure support for 5.4 and 5.5 at 1.0.
• [x] Unit tests in this package rather than relying on the demo app to test package is working. ~~Add json-api:cache and json-api:clear commands to cache the ApiInterface object. This will give a performance benefit to HTTP requests along the lines of route:cache.~~

Required Internal Changes

• [x] Rename the Resource class as it is a reserved word in PHP 7.0
• [x] Extract StandardObjectInterface and related generic classes to a separate utility library.
• [x] Single ValidatorErrorFactoryInterface in the cloudcreativity/json-api package rather than extending that interface in laravel-json-api.
• [x] Ideally stop injecting HttpServiceInterface and instead inject the ApiInterface and RequestInterface directly. This is possible as long as no services are created post the JSON-API middleware running.

Opening this issue so that people can comment on any features that they think are needed for 1.0.

Hello, I'd like to know if the package has any way to convert an object model to a json with the jsonapi structure in any controller (not necessarily an Eloquent jsonapi controller).

Thank you!

Hi,

First of all, thanks for your work on this awesome project..

I'm current;y investigating the possibility of adding meta information to the attributes validation errors returned when creating/updating resources (as per JSON-API v1.0 specs, https://jsonapi.org/format/#error-objects).

My use case would be to add a machine-readable description of each validation error, to complement the human-readable one found under "details"... Something like :

{
    "status": "422",
    "title": "Unprocessable Entity",
    "detail": "The status must be between 1 and 5.",
    "source": {
        "pointer": "/data/attributes/status"
    },
    "meta": {
        "machine_description": {
            "between": [
                "1",
                "5"
            ]
        }
    }
}

With Laravel, calling $validator->failed() returns a pretty decent (when JSON-encoded) machine-readable description of all errors, for example, given the following rules :

[
 'title' => 'bail|required|string|min:5|max:10',
 'pages' => 'bail|required|numeric',
 'body' => 'required|string|same:title|not_in:foo,bar',
 'else' => 'required',
 'comments' => 'bail|min:3',
 'comments.*.author' => 'bail|required|string',
]

and the following attributes :

{
	"title": "foo",
	"pages": "a",
	"body": "foo",
	"else": "test"
}

$validator->failed() would return something like this :

{
    "title": {
        "min": [
            "5"
        ]
    },
    "pages": {
        "numeric": []
    },
    "body": {
        "notin": [
            "foo",
            "bar"
        ]
    }
}

Anyway... the actual use of this feature is not important here, my question is simply : it is currently possible to add meta info to error objects? If not, where should I begin to investigate in order to achieve such a thing?

Maybe a new method (getMeta) could be added to the AbtractValidators class, which would access the validator instance and the error path (source/pointer), the return value being added as meta to the error?

Thanks for your help...

I'm evaluating the use of this library for a rewrite of our API.During my tests I wanted to create a custom controller and used this:

$api->resource('model', ['controller' => true]);

What about detecting controllers automatically based on the by-resource setting?

• true ➡ App\JsonApi\Model\Controller
• false ➡ App\JsonApi\Controllers\ModelController

What do you think about this? Is it hard to realize?

Hi there,

I'm almost done updating my full application to this library, which btw is simply amazing, only to face a last minute issue. Let me explain. Consider a Post with many Comments.

Using related resources I can have the following endpoint: /api/posts/{post_id}/comments

Now I would like to implement pagination on this and I know it is on the path to 1.0, that's awesome news. But I also need to be able to include other resources or apply some filters.

But the following doesn't work: /api/posts/{post_id}/comments?include=author&filter[title]=hello

I would have expected that it would be parsed by the Comment Adapter and Validator. I don't see anything in the spec preventing filtering or inclusion on related resources, unless I missed it.

Sure I could achieve the same result by adding a filter on the comments endpoint: /api/comments?include=author&filter[title]=hello&filter[posts-id]={post_id}

But that's not how my API is documented and isn't the best way of doing it.

Is it something which is on the radar? Maybe on the road to 1.0?

I am working with passport scopes to authenticate specific actions. First of all, I ran into the issue that the scope middleware, provided by passport, does not play nicely with the json-api. For Example $api->resource('my-resource')->only('index')->middleware('scope:my-resource:index'); only returns a 500 internal server error instead of the 403 with details on the missing scope. As an alternative, I'd like to move the logic from the routes file to the authorizer. Unfortunately, I don't see any possibility to customize the response error text for the authorization exception, since the api only returns {"title": "Unauthenticated"} along with the 403 response code.

Is there any possibility to customize the response like "You need scope XY to access this resource"?

Hi. i'm trying upgrade rc2 to 1.1 and all time i seeing message "Class json-api does not exist", so Facade can't be loaded Maybe i should load custom service provider somewhere or i hand't done something at configs? P.S. app namespace isnt 'App/', but i changed 'namespace' in the config file P.P.S. Maybe i should add 'CloudCreativity\LaravelJsonApi\ServiceProvider::class,' to providers ? but didn't see it at the dummy app

Hi! This POST-request create row in many-to-many table:

{
  "data": {
    "type": "legal-entity-warehouse-days",
    "attributes": {
    },
    "relationships": {
      "legal-entity-warehouse": {
        "data": {
          "id": "8",
          "type": "legal-entity-warehouses"
        }
      },
      "warehouse-day": {
        "data": {
          "id": "1",
          "type": "warehouse-days"
        }
      }
    }
  }
}

In table legal-entity-warehouse-days has unique key (legal_entity_warehouse_id - warehouse_day_id).

If you send a post request several times, there will be an error duplicating a unique composite key.

How to fix it?

Hello, How do i make a request to one resource endpoint without using an http client? Here is my problem I have create a controller to update the current user informations. I have a users ressource configured. When i try to create a request like this and pass it to the app()->handle() functions the request fails with a 500 error :

$request = Request::create( '/api/v1/users/1', 'POST', $data, ); $response = app()->handle($request);

is there a way to call a ressource controller action without using an $httpClient?

I want to migrate from cloudcreativity/laravel-json-api to laravel-json-api/laravel.

I have too much code that I don't want to migrate when starting a new laravel project. Can I install both libraries in one project?

I have a problem with one dependency library that is different version laravel-json-api/encoder-neomerx

• ^1.0 in cloudcreativity/laravel-json-api
• ^2.0 in laravel-json-api/laravel

Problem 1
    - laravel-json-api/laravel[v2.0.0, ..., 2.x-dev] require laravel-json-api/encoder-neomerx ^2.0 -> satisfiable by laravel-json-api/encoder-neomerx[v2.0.0, 2.x-dev].
    - laravel-json-api/encoder-neomerx[v2.0.0, ..., 2.x-dev] require laravel-json-api/neomerx-json-api ^5.0 -> satisfiable by laravel-json-api/neomerx-json-api[v5.0.0, 5.x-dev].
    - You can only install one version of a package, so only one of these can be installed: laravel-json-api/neomerx-json-api[v1.1.0, v1.x-dev, v5.0.0, 5.x-dev].
    - cloudcreativity/laravel-json-api[v4.0.0, ..., 4.x-dev] require laravel-json-api/neomerx-json-api ^1.1 -> satisfiable by laravel-json-api/neomerx-json-api[v1.1.0, v1.x-dev].
    - Root composer.json requires cloudcreativity/laravel-json-api ^4.0 -> satisfiable by cloudcreativity/laravel-json-api[v4.0.0, 4.x-dev].
    - Root composer.json requires laravel-json-api/laravel ^2.0 -> satisfiable by laravel-json-api/laravel[v2.0.0, v2.1.0, 2.x-dev].

@lindyhopchris Is there a possibility that this will happen?

Given something like:

$api->resource('foo')
  ->relationships(static function (RelationshipsRegistration $relations) {
    $relations->hasOne('bar');
    $relations->hasOne('fizz');
    $relations->hasMany('buzz');
  })
  ->middleware('example');

How can I specify a middleware for the buzz relationship independent of bar and fizz (and the main resource)? Something akin to this is what I'm looking to do:

$api->resource('foo')
  ->relationships(static function (RelationshipsRegistration $relations) {
    $relations->hasOne('bar');
    $relations->hasOne('fizz')->middleware('cache.headers:public;max_age=604800');
    $relations->hasMany('buzz');
  })
  ->middleware('cache.headers:public;max_age=600');

On that same topic, is there a way to setup different middleware per resource endpoint? I'd like to be able to target the index separately from the individual item. I have a workaround where I split out the resource into multiple definitions using ->only('index') but it seems clunky.

When I have a model with multiple primary keys I get a SQL error.

SQLSTATE[42000]: Syntax error or access violation: 1064 You have an error in your SQL syntax; check the manual that corresponds to your MySQL server version for the right syntax to use near 'as `` asc limit 5 offset 0' at line 1 at /var/www/v2/laravel/vendor/doctrine/dbal/lib/Doctrine/DBAL/Driver/PDOConnection.php:79)
[stacktrace]