Hey,
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?
Tx,
Sigi
From:
tractusx-dev <tractusx-dev-bounces@xxxxxxxxxxx> on behalf of tobias.zahn--- via tractusx-dev <tractusx-dev@xxxxxxxxxxx>
Date: Tuesday, 12. December 2023 at 08:51
To: paul.latzelsperger@xxxxxxxxxxxxx <paul.latzelsperger@xxxxxxxxxxxxx>, tractusx-dev@xxxxxxxxxxx <tractusx-dev@xxxxxxxxxxx>
Cc: tobias.zahn@xxxxxxxxxxxxxxxxx <tobias.zahn@xxxxxxxxxxxxxxxxx>
Subject: Re: [tractusx-dev] Proposal: TRG for API Versioning
Hello Paul,
thanks for your reply.
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.
There is a whitepaper by the association on backward compatibility which can be found here:
https://catena-x.net/fileadmin/_online_media_/231006_Whitepaper_LifeCycleManagement.pdf. Therefore I think we also need some guidelines on how the versioning should be handled, as I see this as a prerequisite for compatibility.
Best regards
Tobias
Von: Paul Latzelsperger <paul.latzelsperger@xxxxxxxxxxxxx>
Gesendet: Montag, 11. Dezember 2023 20:26
An: tractusx developer discussions <tractusx-dev@xxxxxxxxxxx>
Cc: Zahn, Tobias (050) <tobias.zahn@xxxxxxxxxxxxxxxxx>
Betreff: Re: Proposal: TRG for API Versioning
[**EXTERNAL E-MAIL**]
Hey all,
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”
Thanks for reading,
Best
Paul
Hello developers,
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.
While there are rules in Catena-X for compatibility (see the whitepaper at
https://catena-x.net/fileadmin/_online_media_/231006_Whitepaper_LifeCycleManagement.pdf),
there is not yet a clear rule in Tractus-X how APIs should be versioned. However, there cannot be any compatibility without versioning.
Therefore, I would like to suggest adding an TRG regarding API versioning to Tractus-X. I have created a proposal as a pull request on GitHub at
https://github.com/eclipse-tractusx/eclipse-tractusx.github.io/pull/526
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
Tobias F. Zahn
Mercedes-Benz AG
ITO/XA
HPC Werk 050 / HPC G 288
71059 Sindelfingen
Mobil: +49 176 30955133
email: tobias.zahn@xxxxxxxxxxxxxxxxx
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.
|
|
