Guidlines for using jar as a dependency

[NilayBhatt]

Is your feature request related to a problem? Please describe.
As a user, I would like to use this senzing api server as a dependency and wrap some custom code around it. What are the guidelines and usage patterns for such a use case?

[barrycaceres]

We actually do this in our app, but it might depend on your use case.

Before I deep-dive in the how-to, let me describe two scenarios:

1. Leverage the REST API and create another Senzing REST API as a facade in front of the Senzing REST API. This would mean that the user's inbound HTTP request would trigger one or more additional HTTP requests against the Senzing REST API server using a Java client (which I am working to create for you). You would also have to stand up two API servers.

2. Leverage the classes in the REST API server directly by initializing it with your own implementation of SzApiProvider (this is what we do in our app).

The problem with #2 is with backwards compatibility between minor and patch releases. We use semantic versioning to describe which upgrades will maintain backwards compatibility for the REST API. This means that version 1.8 should be backwards compatible with 1.7 if you are consuming the REST API (scenario #1 above). However, that same thing does not apply to the Java classes contained in the API Server (scenario #2 above). We do not guarantee backwards compatibility for the classes in the API Server JAR.

For example, the com.senzing.api.services.AdminServices.heartbeat(UriInfo) method handles the GET /heartbeat REST API call. Imagine if we added a new query parameter for GET /heartbeat such as GET /heartbeat?withDetailedInfo=true. We would likely just add a new parameter to Java function so it would now be com.senzing.api.services.AdminServices.heartbeat(boolean, UriInfo) and any calls you made directly to that function would then fail to compile unless you began passing a value (even a default value) for that parameter.

The bigger one is the com.senzing.api.services.SzApiProvider interface which may gain additional methods that you would be required to implement in an upgrade. For example, when functions dealing with entity types and entity classes were added, this interface was required to provide the set of known entity types and entity classes from the currently active config (usually cached and updated if the config changes to improve performance).

So which route were you thinking?

[NilayBhatt]

@barrycaceres I am thinking more about using the first method as it makes more sense for me