[RFC] Deprecate support for Resource Entity Separation

I would like to propose to deprecate the Resource Entity Separation feature. This feature allows different models to be used in the service layer and repository layer. See this example project

I propose to deprecate it because of the following reasons

1. It is unfinished The feature is not well maintained, not documented and not production ready. Even though all tests related to this example project are passing, there are many cases that are not covered and I’m sure many of them will fail (compare with coverage of JsonApiExampleTests). Still, there haven’t been any bug reports about this, which probably means this feature isn’t used a lot in production. This wouldn’t surprise me because there is no documentation about this feature.

2. Usecase is unclear It is unclear (at least to me) what problem is solved by being able to use a different class in the service layer vs repository layer. There are no indicators about this in the example project because there are no notable difference between the entity and resource model.

The only (incomplete) usecase I can come up with is wanting to have multiple “views” (resources) for one database entity. I am however not sure why allowing for resource entity separation would be the best/only approach to supporting something like this. For example: if the goal is changing the API output depending on authorization, transforming the data can be achieved by leveraging Resource Hooks. Even if there is a valid usecase, I’m still wondering if the extra complexity introduced by the support for resource entity separation outweighs the advantages of keeping ithe codebase simple.

3. Supporting it would greatly postpone time to production readiness Adding this feature adds a great layer of complexity: every feature needs to be supported for the cases of “normal” usage (non-separated) as well as for usage with resource entity separation. This means that for release of v4, a great deal of work has to be put in in identifying and covering the unsupported use-cases, and new features like Resource Hooks also need to be compatible. The release of v4 would be postponed for a great amount leaving it in a not-production ready state for a longer period of time.

In conclusion Even if resource entity separation turns out to be useful in certain situations, with the limited development capacity that we have I don’t think it is worth maintaining it.

The repository history shows that @roblankey was the main contributor for this feature. I would be grateful to hear your thoughts on this. What was your motivation for this feature?

Any thoughts are welcome.

[roblankey]

Sorry folks, been a little bit since I’ve monitored this issues here. Thanks for reaching out on LinkedIn to let me know @maurei .

The primary driving factor for the Entity/Resource split is that Entity models are occasionally, if not often, different from Resource models in a service design. It allows a separation of concerns, hidden/remapped components, many-to-many relationship conversation (since that doesn’t exist in the JSON-API spec), and potential security separation. I haven’t updated the library in a while on my code base, so unfortunately, I’m not certain if there are issues with it now. I haven’t been actively updating it either.

On the other hand, it does add a significant layer of complexity, so removing it would definitely simplify things. And since everything is in Git, if it ever came back up, it would be something that could theoretically be pulled back in or forked.

[maurei]

As it turns out that a (significant) part of the usecases for ER separation are now covered by other parts of the framework (ResourceHooks, HasManyThrough), I think we will remove it for now. Still, having better separation of concerns by allowing for such split would be a really good feature to re-add in the future, but for now the development capacity is too limited to support it.