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.
|