Hello everyone,
the point mentioned
> 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.
I am aware of the decision record at
https://github.com/eclipse-edc/Connector/tree/main/docs/developer/decision-records/2023-11-09-api-versioning, but I belief there should be a TRG on this.
Tobias
Von: tractusx-dev <tractusx-dev-bounces@xxxxxxxxxxx>
Im Auftrag von Hellmeier, Malte via tractusx-dev
Gesendet: Dienstag, 12. Dezember 2023 15:00
An: tractusx developer discussions <tractusx-dev@xxxxxxxxxxx>
Cc: Hellmeier, Malte <Malte.Hellmeier@xxxxxxxxxxxxxxxxxx>
Betreff: [Caution: digital signature was invalid] Re: [tractusx-dev] Proposal: TRG for API Versioning
[**EXTERNAL E-MAIL**]
Hi,
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:
https://catena-x.net/fileadmin/_online_media_/231006_Whitepaper_LifeCycleManagement.pdf
https://confluence.catena-x.net/x/CYDMBg
Best regards
Malte
--
Malte Hellmeier, M. Sc.
Fraunhofer-Institut für Software- und Systemtechnik ISST
Wissenschaftlicher Mitarbeiter Logistik
Speicherstraße 6, 44147 Dortmund, Germany
Telefon +49 231 97677-464
malte.hellmeier@xxxxxxxxxxxxxxxxxx
www.isst.fraunhofer.de
--------------------------------------------------------------------------------------------------
Folgen Sie uns:
Hi,
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.
But your own Decision Record states all those reasons anyway:
https://github.com/eclipse-edc/Connector/tree/main/docs/developer/decision-records/2023-11-09-api-versioning
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.
Bye,
Sigi
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.
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
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
[**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.
|
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.
|