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.
Until later
Paul
On 14.12.2023, at 08:55, tobias.zahn--- via tractusx-dev <tractusx-dev@xxxxxxxxxxx> wrote:
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.
Tobias
[**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:
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
--------------------------------------------------------------------------------------------------
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.
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.
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.
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
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
|