Hello all,
happy new year to all of you.
Thanks for adding to the discussion regarding the versioning TRG in December. Your feedback has helped me to improve the TRG and I have incorporated several changes based on the discussion.
While I still belief we need the TRG, we also discussed in the office hour that we need to involve more people in the discussion. Therefore, I was asked to open an discussion in GitHub,
which is what I did.
You can find the discussion here:
https://github.com/eclipse-tractusx/eclipse-tractusx.github.io/discussions/580
Please feel free to add your feedback there.
Thanks
Tobias
Von: Paul Latzelsperger <paul.latzelsperger@xxxxxxxxxxxxx>
Gesendet: Freitag, 15. Dezember 2023 10:13
An: tractusx developer discussions <tractusx-dev@xxxxxxxxxxx>
Cc: Zahn, Tobias (050) <tobias.zahn@xxxxxxxxxxxxxxxxx>
Betreff: Re: [tractusx-dev] Proposal: TRG for API Versioning
[**EXTERNAL E-MAIL**]
Hey all,
I believe we should ultimately hash this out on today’s Office Hours, but I have yet to see a
technical reason, why it is necessary to prescribe to an application, how they should perform versioning. Even saying that the version must contain
/api/v1 is making an assumption about the implementation of the URL structure of an API which I would reject.
It may be understandable to want everything to “look the same”, but to me, the same argument could be made about almost every aspect of an application, but more importantly, it's not a strong enough argument to encroach on applications
for the following reasons.
Neither Catena-X nor Tractus-X are one application, thus we shouldn’t treat it as a monolith. That perception seems to have taken root, unfortunately. If a developer comes in contact with several subprojects/apps, I would expect
them to read documentation about each and every one anyways.
The decision record in EDC was made specifically for EDC APIs, that are all interrelated to a large extent. For example most of the EDC APIs ultimately deal with the same domain, all EDC components are based on the same core code bas, share
the same module structure and follow the same core principles.
The situation in Tractus-X is fundamentally different, in that there are much more subprojects, most of which share litte to no commonality, least of all with EDC. In that sense, EDC as a project is much more tightly knit than T-X.
That said, I completely understand the issues an API version in the header would bring, and frankly, I would not do it that way, nor have I never seen it done in practice.
> My argument would have been alignment across Tractus-X, good Developer experience for outside contributions and usage, easy / fast onboarding to have more traction etc.
Is exactly why I am proposing this.
The reason to put the version number into the URL of APIs and not into the header or elsewhere is exactly to have a common way of versioning APIs which can be understood by everyone. I have discussed different approaches
with some stakeholders, and it was widely preferred to have one way and not different options, for the reasons mentioned above. Putting the version into the header
for example was seen critical by some stakeholders, as not all applications can understand it, it is easy to overlook and it seems to be filtered out by some firewalls in some companies.
Note that the TRG does not say how many digits of the version number should be put into the URL, so every API could decide for /api/v1/ or /api/v1.0/ or
even /api/v1.0.0/. While some people I discussed this with would have preferred more standardization, most people preferred to give more liberty to the APIs in this case.
commenting on your point:
> “I’m honestly more surprised that this hasn’t been discussed in Tractus-X before, I would have assumed something like this got defined on the Software Architecture level.”
I am not part of this Software Architecture level, but I found different sources and first discussions. Not all of them are public available. I just wanted to share them here:
Fraunhofer-Institut für Software- und Systemtechnik ISST
Wissenschaftlicher Mitarbeiter Logistik
Speicherstraße 6, 44147 Dortmund, Germany
Telefon +49 231 97677-464
--------------------------------------------------------------------------------------------------
I’m actually now slightly confused tbh.
My argument would have been alignment across Tractus-X, good Developer experience for outside contributions and usage, easy / fast onboarding to have more traction etc.
I’m honestly more surprised that this hasn’t been discussed in Tractus-X before, I would have assumed something like this got defined on the Software Architecture level.
In worst case scenario, a discussion would have showen that the EDC has versioning X and others have different requirements and we can’t align, but I assume this might be a little bit late now to rework everything on
alignment. While I’m a big fan of doing this like this as the benefit in the longterm is always higher than not doing it.
Sorry, had previously forgotten to “Reply All”:
Requiring that APIs be versioned is understandable and a good idea, no argument there. But mandating the versioning scheme of an API is akin to mandating all APIs must return the same JSON schema in the response, just
because then every app is doing it the same way.
I have yet to hear (or understand) an argument why all APIs in Catena-X must be versioned the same (including minor and patch versions, no less!) other than “because we want it to be the same”. If you could point out
a technical reason for this, I would be grateful.
Typically, applications that use any particular versioning scheme (URL-style, accept-header,…) do so because there they have good reason to do so and we can’t just preempt that decision for them. For example EDC captured
this in a decision-record.
We really do have different versioning behavior inside Tractus-X?
Honestly, if I’m a developer, I would find this very very shitty and I also don’t think a versioning schema is an implementation detail.
The programming language or business logic is an implementation detail.
Have you all not talked about something like this before?
Let me answer inline below in green.
In general, I do not think that simply listing some recommendations is not enough. As we are one dataspace, all standardized APIs should behave in a similar manner and not entirely different. That still allows venders
to use completely different mechanisms for their internal or proprietary APIs.
While I agree in principle that versioning APIs is a good idea, especially if they are consumer-facing, I disagree with the TRG as currently drafted in the following aspects:
-
How exactly APIs are versioned, i.e. “/v2” and “/v3” vs header parameter etc. is an implementation detail and does not belong in a TRG much less
in a standard à I
think it does, because since this is one dataspace all APIs should behave in a similar way. I do not think this is an implementation detail. What happens behind the API can still be done differently by each vendor.
-
3xx redirects are not useful, especially if APIs have breaking changes, which is typically the case when increasing the (major) version à It
is basically a way of communicating where the API can be found now, but maybe we can make this a SHOULD.
-
Some applications, such as Tractus-X EDC may not have control over all APIs (DSP, IATP,…) à Agreed.
I was thinking about the use cases, portal, etc.
-
Such a TRG will be very hard to enforce anyway, at least statically à I
am not sure what you mean here, sorry
-
There is no functional reason to require all applications to use the same API versioning scheme. Client application implementors will need to read the API doc anyway. àAgain,
I belief that all standardized APIs in the data space should behave in a similar manner. That does not included non-standardized APIs used in proprietary software.
-
Some aspects of the TRG are beside the point of versioning. While some projects may certainly welcome recommendations on how URLs should be structured, it ultimately has nothing to do with versioning and should be entirely up to the application. à for
example?
As far as I am aware comments to that effect have been made on the aforementioned Pull-Request.
While I do understand and support the need to ensure compatibility, I emphatically disagree with the notion of prescribing implementation details to applications. There is more than one way to achieve compatibility, and
there is no point in requiring any particular one.
Instead of mandating impl details in a TRG, my suggestion would be to issue a set of coding best practices and recommendations that could include API versioning, e.g.:
-
“APIs should be versioned to ensure compatibility.”
-
“Deprecated APIs should be marked accordingly, e.g. in OpenAPI documentation”
-
“Deprecated APIs should be kept at least for one release cycle”
-
“Several well-known versioning schemes exists, such as URL path versioning or putting the version in a custom request header or the accept header”
many APIs in the world and also in Catena-X are versioned in order to ensure that changes on API-level are clearly identifiable. Also, versioning APIs enables backward compatibility, as one could choose to offer different
versions of an API in parallel.
Your feedback is highly appreciated.
Please feel free to give feedback on the TRG on GitHub or reach out to me via email.
Kind regards
Mercedes-Benz AG
ITO/XA
HPC Werk 050 / HPC G 288
Mercedes-Benz AG, Stuttgart, Germany
Sitz und Registergericht/Domicile and Court of Registry: Stuttgart, HRB - Nr./Commercial Register No. : 762873
Vorsitzender des Aufsichtsrats/Chairman of the Supervisory Board: Bernd Pischetsrieder
Vorstand/Board of Management: Ola Källenius, Vorsitzender/Chairman; Jörg Burzer, Renata Jungo Brüngger, Sabine Kohleisen, Markus Schäfer, Britta Seeger, Hubertus Troska, Harald Wilhelm
|
If you are not the addressee, please inform us immediately that you have received this e-mail by mistake, and delete it. We thank you for your support.
|
|
If you are not the addressee, please inform us immediately that you have received this e-mail by mistake, and delete it. We thank you for your support.
|
If you are not the addressee, please inform us immediately that you have received this e-mail by mistake, and delete it. We thank you for your support.
_______________________________________________
tractusx-dev mailing list
tractusx-dev@xxxxxxxxxxx
To unsubscribe from this list, visit https://accounts.eclipse.org
If you are not the addressee, please inform us immediately that you have received this e-mail by mistake, and delete it. We thank you for your support.
|
