Best practice for bidirectional external API mapping?

[tobias-grasse]

My application needs to synchronize models (= read & write) with a third-party JSON REST API. It looks like laravel-data is a great fit for that purpose, but I wonder what the best practices for this use case are.

1. Do you keep the DTO aligned with the corresponding models, or with the external API?
2. In either case, how do you keep the mapping simple?
3. What's the sanest approach to serialize and de-serialize related models? Assuming that all relations are eager-loaded.

To explain by example: I need to synchronize my Client Eloquent model with a ClientContact resource on the third-party API.
Some properties need just a name mapping: firstName (API) <-> given_name (Eloquent). Others are more complex: id (API) <-> external_id attribute on the profile relationship of my Client model.

Example API response:

$data = '{
      "id": 123, // must be mapped to $client->profile->external_id
      "dateAdded": 1555427162977,
      "dateLastModified": 1557474876380,
      "clientCorporation": { // mapped to $client->company relationship
        "id": 456,
        "name": "ACME Corp"
      },
      "email": "someone@domain.tld",
      "firstName": "First",
      "lastName": "Last",
      "occupation": "Job title", // mapped to $client->profile->job_title
    }';

ERD of my Eloquent models:

My ClientData object – properties currently aligned with the Eloquent model:

class ClientContactData extends Data
{
    public function __construct(
        #[MapName('dateAdded')]
        #[WithCast(TimestampCast::class)] // Custom cast as API timestamps are milliseconds ¯\_(ツ)_/¯
        #[WithTransformer(DateTimeInterfaceTransformer::class, format: 'Uv')]
        public CarbonInterface $created_at,
        #[MapName('dateLastModified')]
        #[WithCast(TimestampCast::class)]
        #[WithTransformer(DateTimeInterfaceTransformer::class, format: 'Uv')]
        public readonly CarbonInterface $updated_at,
        public string $email,
        #[MapName('firstName')]
        public ?string $given_name,
        #[MapName('lastName')]
        public ?string $family_name,
    ) {
    }

My ideal solution would be something along these lines:

# Create a Client from API response
/* @var string $data example data from above  */
$data = RestApiClient::getClient(123);
$dto = ClientData::from($data);
Client::create($dto->toArray());

# Send a Client via API
$dto = ClientData::from(Client::first());
RestApiClient::updateClient(123, $dto->toArray());

I experimented with the Map{Input,Output}Name attributes and the from<Type> magic methods, but sooner or later I find myself repeating the mapping in both directions. Maybe I'm holding it wrong™?

If I understand the package code correctly, the JsonNormalizer will decode the API response string to an associative array, which is passed to the ClientContactData constructor. Do I need to override both fromArray and fromModel to map both ways?