Hi Marek
> Hello Experts,
>
> apparently, when looking at our EG mailing list, the last week was a very active one, especially when it comes to the
> client API discussions. I wish I was not on a vacation - it took me 2 days to read through all the messages! :)
>
> Until now, I thought that having the API requirements captured in Jira issues is good enough. However, while reading
> those new messages it became obvious that having the requirements listed explicitly would be very useful so that we can
> use the requirements list to asses any new proposals.
Thanks for listing them - recall I was asking for a matrix :-) - but I
guess I understood some requirements during the last week's busy
discussions :-).
Now, what I'd like to propose is to have an over-arching requirement:
all the current and next proposals have to pass a litmus test:
- Is satisfying a given requirement with a given proposal going to help
users write *practical*, *real-world* code which will be realistically
used. If it's going to be of academic interests then it has to be
dropped. Otherwise API will be 'diluted'.
Well, I guess, it's tricky to envisage all the real-world cases users
will want to address with this API. But we should be realistic IMHO
Just my 2c, thanks
Sergey
>
> Let's now take a small step back and try to agree on the main requirements for the client API. I have made an attempt to
> compile all the main requirements from Jira as well as from the recent emails into a concise list[1]. Before we continue
> any further discussion on the Client API, please have a look at the list, review it and send me your feedback.
>
> Thank you,
> Marek
>
> [1]: Client API requirements
>
> - API must support creating & invoking a request and consuming a response
> : Create arbitrary requests using Client instance
> : Create multiple requests to a single resource (simpler, less verbose) using Link instance
>
> - API must support batch request processing
> : Process multiple arbitrary requests using a uniform interface with sync & async support
>
> - API must support sync and async invocations
> : Users must be able to send requests and retrieve responses both synchronously as well as asynchronously
>
> - API must provide a configuration support
> : Properties, features, filters & handlers of each request must be configurable
>
> - API must support configuration inheritance and scoping
> : Configuration must be supported at multiple levels - global (Client), resource-specific (Link), request specific
> (Invocation)
> : Configuration from the parent component is inherited by the child component
> : Configuration of a child component is detached from parent; once a child component is created, subsequent changes in
> the parent component configuration have no effect on the configuration of the child component and vice versa.
>
> - API must support injection of resource clients (Links)
>
> - API must support custom implementations & extensions
> : Users must be able to provide as well as choose a specific (custom) implementation of the Client API
>
> - API must support multiple implementation and/or implementation versions running in a single container at the same time
>
> - API must eliminate possibility to write illegal constructs in the fluent API
> : e.g. invocation.method("PATCH").get();
>
> - API must allign well with the IDE code-completion
> : the IDE code completion should be able to provide relevant hints for the fluent API based on the context
> : e.g. once the entity was set, the IDE would not list the entity() method in the fluent method invocation chain code
> completion again (this is an illustrative example, not satisfiable with the current API)
>