Proposal for an admin REST and GraphQL Server

[gmcrobert]

for Strimzi.

Signed-off-by: Graeme McRobert mcrobert@uk.ibm.com

[ppatierno]

I had a first quick pass. Anyway, it would be great to have one sentence per line. This is the way we follow for documentation as well because it simplifies the review (for how GitHub works) in order to allow us to comment on every single line and not the entire paragraph.

[ppatierno]

what are the "existing" APIs it's referring to?

[ppatierno]

talking about security, how you envisage authn and authz of users for calling REST or GraphQL API?

[gmcrobert]

@ppatierno I have changed the file to have each sentence on a separate line. I will elaborate on the security stuff after I have put some more thought into it. Feel free to add some suggestions. Advice would be most welcome.

[samuel-hawker]

I assume different functionality includes varying methods of authn and authz too? i.e. a mechanism to set different authed endpoints, one scram, one TLS etc?

Or is this handled by the security context piece in the Security section?

[gmcrobert]

I have rewritten this section to clarify the uses and have specifically cited the use of multiple authentication schemes as the main driver for needing to do this.

[scholzj]

I left some questions for clarification. But LGTM overall. Great work, thanks.

[scholzj]

Maybe you can add some examples for clarification what exactly does this mean and what could be the use-case?

[gmcrobert]

I have provided the example of supporting multiple authentication schemes to demonstrate the use case. The idea behind this is to provide something similar to the advertised listeners in Kafka.

[scholzj]

What is the value and the cost of supporting both REST and GraphQL? Not just for development, but also QE, maintenance etc.

[gmcrobert]

I do not think it will add a huge amount of overhead supporting both. Both APIs will be retrieving similar data but in a slightly different way. This allows the collection and aggregation of the information to be done in a way that is common to both and the difference then becomes a small piece on top that formats the results slightly differently. Both apis still use a REST endpoint with the main difference being that the REST api has multiple resource paths and each path represents a resource whereas GraphQL has a single resource path and the different resources to be returned are defined in the payload so similar tools can be used to test both APIs. Both APIs will also be implemented using the Vert.x libraries so keeping the libraries in-sync should be straightforward.

[dlabaj]

lgtm

[scholzj]

Thanks for the proposal

[scholzj]

I added it to the agenda for tomorrows community meeting to push others to review as well ...

[tombentley]

My main comment here is about defining the URL structure of the API with respect to plugins from multiple vendors and supporting multiple API versions.

[tombentley]

While I don't have a problem with this in principal, I think we need to ensure that the URL structure of the API reflects the identity of the service and also its version. This is to prevent two different plugins (e.g. from different vendors) using the same name and also to provide API evolution between different versions of the same plugin (it's not clear to me whether a service could provide more than one API version).

[gmcrobert]

@tombentley is it sufficient that the mount point cannot be empty (the root) and must be unique or were there other restrictions you had in mind? The versioning is a little more challenging because the world has moved away from versioning being present on the URI. A common way to version is to use the media type so, e.g. you would have application/vnd.strimzi.v1+json, application/vnd.strimzi.v2+json, etc and the type without versioning, i.e. application/json would always refer to the latest version. Do we want a registration object which allows an added service to specify its mount point, version and anything else that would be useful, e.g. a vendor identifier, but not include the version in the URI? This would of course imply that you couldn't have more than 1 version of the API loaded which makes sense as a true REST API has the same limitation. Handling different version is then the responsibility of the implementor of the API.

[tombentley]

I don't have a strong preference for including the version in the URL and TBH I wasn't aware of a trend to use media types instead. That said, I think there is some value, for people how know Kubernetes' REST API, in doing something similar with api groups at least. So if it were me, I would be envisaging

• GET / would return some description (presumably openapi) of the available endpoints
• The common, strimzi provided plugins might live under /strimzi.io/... or even /core.strimzi.io/..., to allow for other Strimzi api groups in the future.
• Plugins provided by some vendor might live under /example.com/...

[tombentley]

Suggested change

	For example, lets assume that strimzi only implements a Kafka administration API which provides a set of APIs based around the Kafka Admin Client.
	For example, let's assume that Strimzi only implements a Kafka administration API which provides a set of APIs based around the Kafka Admin Client.

[gmcrobert]

I will correct my colonial english ;-)

[tombentley]

Would this really be classpath-based, or use java modules?

[gmcrobert]

When I originally wrote this, Strimzi had only just made the switch from Java 8 to Java 11. The update I did the other day I was trying to be agnostic of the two versions because I wasn't sure whether we were ready to exploit Java 11 as a community but I obviously failed. My preference is definitely use the Java 11 modules in which case this statement will need to be updated. If you agree that it should be Java 11 modules then I will update the document to be specific and correct.

[tombentley]

Suggested change

	A secondary benefit of a modular approach is that it allows the strimzi user to configure the server to only contain the functionality that they would like to use providing for a leaner server.
	A secondary benefit of a modular approach is that it allows the strimzi user to configure the server to only contain the functionality that they would like to use, providing for a leaner server.

[tombentley]

So with reference to my previous comment, I'm not sure if any plugin should be bindable to the root path. The root path could be used for discovery of the API provided.

[gmcrobert]

So if the response in the previous comment is sufficient.

[tombentley]

Oh, one other thing: API should be spelt in upper case. "REST api" is a little jarring.

[scholzj]

@tombentley Is this now OK for you?

[tombentley]

Suggested change

	A handler can decided whether the request should be passed on to the next downstream handler or the request is complete and the downstream handlers should be bypassed and they have access to the full request through the routing context.
	A handler can decide whether the request should be passed on to the next downstream handler or the request is complete and the downstream handlers should be bypassed and they have access to the full request through the routing context.

[scholzj]

Thanks for the proposal.