Hi Carsten
OpenAPI integration and the implementation go hand in hand so no reason
separating them. I think what this draft does is just trying to see how
this might work. I am also parallelly working on OpenAPI spec but I wanted
the developers to review this work to get a better understanding of how to
proceed further.
As for the PATCH example that I quoted, that was just for
demonstration purposes to show the two approaches.
Best Regards,
Girish
On Wed, Jun 17, 2020 at 2:42 PM Carsten Schinzer <
cars...@dcs-verkaufssysteme.de> wrote:
> Hello Giresh,
>
>
> Thanks for the example, it makes clearer what you want to achieve.
>
> General considerations on RESTful or not:
> If you want to stop a productionRun, why do you use PATCH and not DELETE?
> Well, I know the connotation of Delete is „dismantle“ rather than „stop“,
> but PATCH also considers and exposes config/data changes, not only status
> changes
>
> PATCH /rest/productionruns/{productionRunId}?action=cancel
> … would probably be the best
>
> Here is how an Annotation based implementation would achieve this:
>
> @Route /productionrun/{productionRunId}, requirement={productionRunid, \d+}
> @ApiDoc(title=„A service to patch MRP Production Runs“, description="It
> allows to change the run configuration and status“)
> public patchProductionRunAction(int productionRunId, string[]
> urlParameters)
> {
> ...
> if urlParameters[‚action‘] == ‚cancel‘:
> call service cancelProductionRun(productionRunId)
> ...
> }
>
> Forgive this pseudo-code, but I think you get what I mean.
>
> It would not avoid that some matching layer of code is reuqired in-between
> the exposed REST API methods like patchProductionRunAction and the actual
> service call, but this layer would remain code instead of being in XML or
> somewhere else that requires a context switch.
>
> In my other application (the PHP) the classes are clearly separated by
> responsibility, i.e. Repository classes interact wit the persistence layer,
> Service classes are manipulating things and RestController classes are
> wrapping up the REST API methods and properly annotated with the Routes and
> validation constraints. The important point is that it is all coded in the
> same language and therefore the context is exposed to the IDE I am working
> with. No lookups to be made into an XML file to understand parameters and
> return types of services etc. That is quite an advantage IMO.
>
> IMO that is the complexity in the current way of dealing with this in
> OFBiz and that’s why I believe the OpenAPI integration should be going
> along with REST implementation.
>
> Warm regards
>
>
> Carsten
>
>
> > Am 17.06.2020 um 08:38 schrieb Girish Vasmatkar <
> girish.vasmat...@hotwaxsystems.com>:
> >
> > Hi Carsten -
> >
> > Your points make a lot of sense and that's the general consensus of the
> > community as well. However, I believe we want to have the option of
> > exposing the services via "REST". The existing frameworks services
> > obviously are not named, thinking them as Resources and in the REST work
> > resources are perceived as nouns.
> >
> > This is obviously not a complete implementation and we would obviously
> like
> > to tie up entities and services with resources. For example - consider
> the
> > service cancelProductionRun.
> >
> > If we expose it under services resource (considering services as
> > resources), we could do it like this -
> > PATCH /rest/services/cancelProductionRun
> > {
> > "productionRunId": 1234
> > }
> >
> > While this may not sound RESTFul, but this in a way adds capability for
> > OFBiz to expose the services via a "REST" interface. A truly RESTFul
> > approach that I am working on might do something like this -
> >
> > PATCH /rest/productionruns/{productionRunId}
> >
> > Internally it will hook up the service cancelProductionRun with this
> > resource URL. This obviously has to be configured somewhere in XML and
> such
> > details can be chalked out.
> >
> > Best,
> > Girish
> >
> >
> >
> >
> >
> >
> >
> >
> >
> >
> > On Tue, Jun 16, 2020 at 12:45 PM Jacques Le Roux <
> > jacques.le.r...@les7arts.com> wrote:
> >
> >> Thanks Girish,
> >>
> >> I did not have time to look into details yet but your README is very
> >> promising :)
> >>
> >> Jacques
> >>
> >> Le 15/06/2020 à 17:59, Girish Vasmatkar a écrit :
> >>> Hi All
> >>>
> >>> I have tried to implement a draft proposal here -
> >>> https://github.com/girishvasmatkar/ofbiz-rest-impl.git
> >>> The readme contains details.
> >>>
> >>> In order to support the changes, I have made a corresponding change in
> >> the
> >>> service definition to include a new attribute named "verb". This can
> also
> >>> be named "method". These changes are in my forked ofbiz repo (it is
> very
> >>> much in sync with ofbiz trunk):
> >>>
> >>
> https://github.com/girishvasmatkar/ofbiz-framework/tree/feature/add-service-verb
> >>>
> >>> Initial implementation does not contain OpenApi integration yet. And
> yes,
> >>> we should be fine doing both JSON and YAML.
> >>>
> >>> Please take a look at it and let me know what you think of this. I am
> >> open
> >>> to suggestions, improvements, discussions.
> >>>
> >>> Best Regards,
> >>> Girish
> >>>
> >>>
> >>> On Mon, Jun 15, 2020 at 7:02 PM Pritam Kute <
> >> pritam.k...@hotwaxsystems.com>
> >>> wrote:
> >>>
> >>>> Hello Girish,
> >>>>
> >>>> +1 for having REST implementation using Jersey as a separate plugin
> and
> >> not
> >>>> to disturb the OFBiz default Control servlets and filters.
> >>>>
> >>>> IMO we should also think about the end-point security implementations
> >>>> alongside as it is one of the crucial things that users look into
> while
> >>>> adopting any framework.
> >>>>
> >>>> Kind Regards,
> >>>> --
> >>>> Pritam Kute
> >>>>
> >>>>
> >>>> On Fri, Jun 12, 2020 at 2:58 PM Jacques Le Roux <
> >>>> jacques.le.r...@les7arts.com> wrote:
> >>>>
> >>>>> Hi Girish,
> >>>>>
> >>>>> Inline...
> >>>>>
> >>>>> Le 10/06/2020 à 17:42, Girish Vasmatkar a écrit :
> >>>>>> Hi All
> >>>>>>
> >>>>>> I am again bringing up this discussion on having a REST
> implementation
> >>>>> for
> >>>>>> OFBiz. I know we have had discussions before and I was looking at
> some
> >>>> of
> >>>>>> the past discussions about this topic and seems we are not there
> quite
> >>>>> yet
> >>>>>> (correct me if I am wrong).
> >>>>>>
> >>>>>> I had developed a POC plug-in based on Jersey (that I am currently
> >>>>>> enhancing) and recently started evaluating Apache Juneau as well. I
> >>>>> wanted
> >>>>>> to bring everybody on the same page as far as REST implementation is
> >>>>>> concerned so I had initiated a discussion on slack today. I am
> listing
> >>>>> down
> >>>>>> a few points below that can be perceived as
> >>>>> comment/question/understanding
> >>>>>> based on my general understanding of the matter and today's slack
> >>>>>> discussion.
> >>>>>>
> >>>>>> - Anything we start on can be part of a plug-in for the start
> and
> >>>>> later
> >>>>>> can become part of the framework (as separate plug-in) once it
> is
> >>>>>> developed. A dedicated API application will allow it to be
> >>>>> lightweight in
> >>>>>> terms of request processing. Should have separate auth mechanism
> >>>>> bypassing
> >>>>>> ControlerServlet/ContextFiler/ControlFilter. I opine we do not
> >> need
> >>>>> the API
> >>>>>> request to go through these three. Please correct me.
> >>>>> Though I did not look at the code (is it already somewhere?) I tend
> to
> >>>>> agree on that.
> >>>>> REST is something else and should not be hampered by those, if it's
> the
> >>>>> case.
> >>>>>
> >>>>>
> >>>>>> - We want to have mechanism to expose services (export=true) to
> >> be
> >>>>>> available as a REST resources. Possibly extending existing
> >> service
> >>>>>> definition by a new attribute verb="get|post".
> >>>>> +1
> >>>>>
> >>>>>
> >>>>>> Also, if we also want to
> >>>>>> expose out REST interface as an OpenApi specification, then it
> >> will
> >>>>>> possibly help if we show in the spec an example of request for a
> >>>>> specific
> >>>>>> service. In that case, the service definition can be expanded to
> >>>>> allow for
> >>>>>> defining a JSON example (in a CDATA element)?
> >>>>> That's an interesting point. Maybe we could prefer YAML over JSON.
> >>>>> Because YAML is a superset of JSON and that could be useful in
> future:
> >>>>>
> >>>>>
> >>>>
> >>
> https://stackoverflow.com/questions/1726802/what-is-the-difference-between-yaml-and-json
> >>>>> But it might complicate things in request bodies...
> >>>>>
> >>>>>
> >>>>>> - Any service that declares one of the verbs and not called
> with
> >>>>>> declared verb will result in 405(Method not found) or
> >> 404(Resource
> >>>>> does not
> >>>>>> exist) error.
> >>>>>> - GET /api/services/{serviceName}?inParams={JSON}
> >>>>>> - POST /api/services/{serviceName} (Request Body will contain
> >> in
> >>>>>> params as JSON)
> >>>>>> - GET /api/services : We list all services(export=true) along
> >>>> with
> >>>>>> HATEOS Links (self link describing where the specific service
> >>>> can
> >>>>> be
> >>>>>> located)
> >>>>> +1
> >>>>>
> >>>>>
> >>>>>> - Do we want to have a similar resource for entities?. I think
> >>>>> entities
> >>>>>> should not be exposed directly as a REST resource even though
> >> they
> >>>>> are a
> >>>>>> good example of being a resource.
> >>>>>> - We can take one day at a time approach here and just start
> with
> >>>>>> exposing services as REST.
> >>>>> I agree, can be decided later...
> >>>>>
> >>>>>
> >>>>>> - Auth : I had provided JWT based auth for the plug-in I had
> >>>>> developed.
> >>>>>
> >>>>> Sounds good to me.
> >>>>>
> >>>>>
> >>>>>> This can further be expanded and allow for Digest auth as well?
> >> Can
> >>>>> have
> >>>>>> separate API endpoint to generate JWT token.
> >>>>> That could definitely be interesting.
> >>>>>
> >>>>>
> >>>>>> Please share your thoughts on this and apologies for long email.
> >>>>> Don't apologize, perfect summary to me :)
> >>>>>
> >>>>> Thank you, this is long awaited and game changing feature!
> >>>>>
> >>>>> Jacques
> >>>>>
> >>>>>> Best Regards,
> >>>>>> Girish
> >>>>>
> >>
>
>
