Input/Output Class Semantics

[ragboyjr]

I'd like to just discuss the overall feature of input/output classes and how they relate to API Platform as a whole. I feel like there are a few blind spots that should be considered and documented accordingly.

Should Input Classes always be ApiP Resources?

I think it should be a hard requirement that Input classes should be marked as Resources since it can cause issues/inconsistencies if not.

1. Only Resources can use the AbstractItemNormalizer

   If input classes aren't resources, you lose the ability to denormalize other relationship objects from IRI string values.

   e.g.

   // example input class
   class CreateBookRequest {
       private $name;
       private $author;
       public function __construct(string $name, Author $author) {
           //
       }
   }

   Input Data

   {
       "name": "Book 1",
       "author": "/authors/1"
   }

   This ONLY works if the input class is also a resource because the AbstractItemNormalizer adds this functionality and it only supports ApiP Resources.

2. Only Resources can use messenger=true flag

3. If it's a resource, then we can use the input class resource shortname when building documentation instead of the md5 of its class name. See More Descriptive Input/Output class names #2487

Are Input Classes Useful outside of Messenger Integration?

Input classes make CQRS a lot easier to achieve within ApiP. You can easily create custom write services while keeping ApiP's defaults for reading which is a best of both world's type of situation. With messenger, you can create a service/command handler that handles the request dto and interact with the domain and create the necessary resource.

This type of service wouldn't be coupled to the framework and usable throughout your system. However, to do the same without Messenger, you'd need to create a Data Persister which feels very framework specific and can be especially odd when you don't ever need to implement the remove method of the data persister.

Considering that you can use messenger as a command bus and don't need any external deps like redis/amqp for it to work, it seems like messenger and input classes should be the defacto way for using input classes.

[soyuka]

To me the Input classes should definitely be tagged as Resources, as you said you loose the benefits of Api Platform by not declaring it as such. Should we specify this in the docs?

We shouldn't tight input classes with messenger just in case.

Just getting back on the names:

Yes but they are still prefixed by the main resource short name. So you’d have to use two same names input in different namespaces for the same main resource to see this conflict

It's a common thing, for example a Category resource that may be used in different namespaces.

[ragboyjr]

Regarding names, if input classes are resources, then we can modify the documentation serializer to just use the short name. So you could disambiguate the example you brought up by changing the shortname.

Re messenger w input classes, what if there was an option or something to where you could a create an ApiResource with default config. So, maybe a new annotation like @ApiDTO which defaults to something like the following:

/** @ApiResource(messenger=true, itemOperations={}, collectionOperations={}) */

Disabling item and collection operations is important because you don't want the DTO to have it's own operations. Enabling messenger by default on the item doesn't actually enforce messenger, unless messenger is actually installed and enabled with api platform.

[ragboyjr]

Or, we could just support another attribute like: @ApiResource(dto=true) which would default those values. Something similar to this: https://github.com/krakphp/api-platform-extra/blob/master/src/Metadata/Resource/SchemaOnlyResourceMetadataFactory.php

[soyuka]

We discussed this with @dunglas and actually the input/output classes should not be declared as ApiResources. I'm going to add a few functional tests this morning and try different combinations before getting back to you.

[ragboyjr]

Ah, ok, that would be very preferable, just seemed like it would require a decent amount of refactoring to get the input classes to deserialize properly and usable with messenger, but would very excited to see what you come up with!

[soyuka]

Yeah, maybe that we just need a quick fix to allow proper relations deserialization.

[dunglas]

We're working on the overall design with @soyuka. We'll publish a new proposal, and updated docs soon.

[soyuka]

I think that we can close this @ragboyjr let me know if there are still issues.