| Re: [hono-dev] Introducing an API version marker |
|
Hi, I think that API versions are a very good idea, especially to define them as early as possible. Of course the very first version could come without versions and only subsequent incompatible changes then introduce a version, but this would IMHO be an ugly workaround. So, to define where we handle the version of an API is best done just now – before we release 0.5. I strongly favour the AMQP 1.0 property idea to handle the API version, and not the target address. How about the different APIs Hono defines? Should we have one common API version for all of them, or are they handled individually? I think that only an API that changes incompatible should update it’s API version, but this will of course lead to something like: -
Hono 1.x contains : registration API V3.0, credentials API V2.0, Messaging API V4.0 and so on. To me it seems ok, though (since it reflects the true situation). Karsten Frank (sysexcontrol) Bosch Software Innovations GmbH Registered Office: Berlin, Registration Court: Amtsgericht Charlottenburg; HRB 148411 B
Von: hono-dev-bounces@xxxxxxxxxxx [mailto:hono-dev-bounces@xxxxxxxxxxx]
Im Auftrag von Hudalla Kai (INST/ECS4) Hi devs, I wonder if we should take the opportunity before doing teh 0.5 release to introduce an "API version marker" into Hono's APIs so that an implementation receiving a request can easily identify which version of the API the client wants to invoke. Given that we are still working on the initial version, it might seem a little pre-mature to start discussing how we identify later versions but I still think it is worth spending some time on the topic. Once we start working on a version 2 of any of the APIs which will then introduce some non-backwards-compatible changes (hence the change in the major version), we need to be able to distinguish a client's request for version 2 from one towards version 1. We might achieve this by means of e.g. adding a version segment to the target address, i.e. using something like telemetry/v1/TENANT instead of just telemetry/TENANT. This pattern is often applied to RESTful APIs using HTTP as the transport. However, since
we are using AMQP 1.0 we could also instead use (or introduce later) an application property "version" which can be included in request messages. FMPOV the latter approach feels more AMQPish. I also think that it would provide for more flexibility because
we would not need to modify the whole address handling code. Any thoughts? -- Mit freundlichen Grüßen / Best regards Registered Office: Berlin, Registration Court: Amtsgericht Charlottenburg; HRB 148411 B |