[Flow] Feedback/call for contribution on a generic Rest API package

[Manuel Mitasch]

Hey!

Yes, totally agree that Flow deserves more REST awesomeness.

I would be happy to help, collaborate and hear your ideas. There are several aspects that I believe are of general purpose for REST APIs. It would make sense to come up with a generic solution and could possibly be included as part of Flow.

1) A service to lookup domain model properties and associations.
2) A general way to configure endpoints for models.
3) A serializer interface + implementation for jsonapi.
4) TypeConverters that handle outgoing content (normally handled by Fluid)

All of this is already implemented in the Flow4ember package and works well. Yes, the package is tailored towards the use with Ember, but easily customizable to other needs. I will give you a short overview of the package.

- Conventional APIs:
It's tailored towards conventional APIs. Thus, every endpoint uses the same conventions for naming and communication. Endpoint names are derived from the model name. In case custom endpoint structure is needed => use the flow router. Properties and associations are extracted from the Flow domain models.

- Configuration of models:
Models for which an endpoint should be provided can be configured through Ember.yaml or Annotations in the model class. It's possible to use flow models from different packages and to rename their meta model name (used to construct the endpoint name) in case models with the same name from different namespaces are used.
github.com/manuelmitasch/Mmitasch.Flow4ember/blob/master/Documentation/Configuration.rst

- Model reflection service:
Obtains the model configuration (resource name, properties, associations) for endpoints. One source of truth!
Could be adapted for different model sources => idea to have one for relational dbs (OrmModelReflectionService), for document dbs (OdmModelReflectionService) and for Neos NodeTypes (NodeTypeModelReflectionService). The consequences for the persistence strategy are not all sorted out.
github.com/manuelmitasch/Mmitasch.Flow4ember/blob/master/Classes/Mmitasch/Flow4ember/Service/ModelReflectionService.php

- Serializer:
Easily interchangeable to serve different formats. Currently EpfSerializer is a not up-to-date jsonapi version (compatible to Ember Data and EPF libraries). It supports associations, sideloading and embedded models.
github.com/manuelmitasch/Mmitasch.Flow4ember/blob/master/Classes/Mmitasch/Flow4ember/Serializer/EpfSerializer.php

Idea: I'm using a customized Fluid parser to kickstart javascript files. Due to the {} syntax of fluid you can not easily parse javascript with fluid. This parser changes the inline syntax from {object.property} to #{object.property}# to enable easy javascript and handlebars parsing. This could be used to construct the output of the serializer. If we would provide a context, we could even use fluids security.if* viewhelpers to hide properties according to security policies.
github.com/manuelmitasch/Mmitasch.Flow4ember/blob/master/Classes/Mmitasch/Flow4ember/Parser/JavascriptTemplateParser.php

- Type converter:
Additional, type converters are needed as Flow only has converters for incoming data. Outgoing data is normally handled by Fluid. The standard types (string, integer, float, date, boolean) are provided through a TypeConverterService. Creation of custom converters is planned, not implemented yet.

- Ember specific: Kickstarting:
Based on the configuration it is possible to kickstart a full blown Ember based CRUD app. It could be easily extended to kickstart Neos backend plugins.

Current status: The package works good. The error handling could be better. In some cases exceptions are thrown, where it would be better to return some meaningful json content. There are some aspects especially around the persistence of associations that need to be reworked. Basically, reading complex model graphs (models connected through associations) is easy with doctrine. Persisting complex model graphs is very hard. Currently it supports only a limited set of association types. Also querying repositories is not well supported.

In February I plan to implement a proper test coverage, rewrite of the persistence strategy and implement a first prototype for a Neos NodeType ReflectionsService.

Regarding cooperation I would suggest that we have a skype or hangout meeting to discuss ideas!?
My next T3 Event will probably be InspiringConf.

Greetings,
Manuel