[META] Make entity API developer friendly

(I am giving only a bref description to this issue too see whether it gets enough attention or not.)

Problem/Motivation

I've been working on to integrate a PHP SDK (API Client) of a REST API to Drupal 8. I thought that in Drupal 8 it is going to be much easier than with Drupal 7 thanks to its new entity architecture, but it seems there are still things to work on to make it more easier for developers.

The PHP SDK parses the API responses to typed objects (SDK entities). An SDK entity class has its own interface that describes all its public behaviors. The SDK entities only data objects, the communication with the API happens through the entity controller classes.

So my initially thought was that integrating the SDK entity classes to Drupal 8 is going to be a child play because the two system is kinda similar to each other. (SDK entity ~ Drupal entity, Entity controller in the SDK ~ Drupal entity storage)

Here is a quick example how I tried to do this. Let it be an FooEntity entity class in the SDK that implements the FooEntityInterface. In Drupal there is an entity, FooDrupalEntity, that extends this FooEntity SDK entity class and also implements the \Drupal\Core\Entity\EntityInterface just to fulfill the minimum requirements. (In theory this should have been enough.)

<?php
namespace Drupal\foo\Entity;

use Drupal\Core\Entity\EntityInterface;

class FooDrupalEntity extends TheSDK\Entity\FooEntity implements EntityInterface {

}

Because I have an entity class in the SDK that can properly transform data returned by the API to an object (typed data structure) I did not want to extend the \Drupal\Core\Entity\Entity class in FooDrupalEntity or use the decorator, proxy or another compatible design pattern to be able to leverage as much as I can from the FooEntity class.

Drupal's EntityInterface requires a bunch of methods to be implemented in our FooDrupalEntity, but it still would be fine. The real problem is that if you would like to implement these methods properly you either have to copy paste them one by one from \Drupal\Core\Entity\Entity (override them if necessary) or find a less nasty way to not to reinvent the wheel again. I found a temporary solution but I would be lying if it would say that I am satisfied with that.

(Not speaking of that if you dig deeper you will surely realize that everything you need is available only for content entities (ex.: persistent caching) out of the box, but you can/do not want to extend content entity related classes so you have to do copy-pasting again.)

Solving this problem would definitely improve the Entity API's code quality too.

Proposed resolution

Create smaller traits from the abstract Entity class and with that allow custom entity implementations to re-use smaller pieces of the core entity implementations if they want. The EntityInterface should be separated to smaller interfaces too.

Remaining tasks

TBD.

User interface changes

-

API changes

Most likely more than 1.

Data model changes

-