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.
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)