Question regarding decoupling the API from the implementing software #952
Comments
|
SemVer absolutely does apply to API's. Just read the spec, particularly the intro. You define what API means, not the spec. There is no reason you cannot independently version your API from its implementations. The API in the spec, stands for Application Programming Interface, not Application Package Interface or Application Implementation Interface, though the way the intro and the spec define API, it's really up to you what it means. There may be some nuanced details to consider, depending on your tool chain and how you package and distribute your code, as well as how your customers package and distribute their code. Are you in any particular vertical environment? The fact that SemVer is mostly implemented by various package management tools in no way implies that SemVer cannot be used to version an API. I have created many independently versioned C# interface packages over the years using SemVer. For a couple of decades prior to SemVer's release, we often used similar/divergent schemes in C (using zip or tar packages), versioning the header files or collections of them, separately from their implementations. It's been a common practice in the embedded systems world, where you have a hardware abstraction layer that provides a common interface and multiple implementations. |
|
Hi @jwdonahue, Thanks for your response. I'm hoping that someone on the maintainers list can confirm your assertion that SemVer applies to the APIs. The feedback I have received where I work contradicts that assertion; backed up by reference to point 1 of the section Semantic Versioning Specification (SemVer) ("Software using Semantic Versioning MUST ...") in the document at semver.org. It's the software that uses SemVer, and not the API, so the argument goes, which I can appreciate (we're a very legalistic lot over here). The other sections in the document are not the specification I am told, and therefore strict adherence to the specification required regarding only the that section.
I'm not at liberty to say.
Our context is that we define APIs for HTTP services (some fully compliant with REST, others not so much) and we document them using OpenAPI. We then share those documents with multiple other organisations who will implement services that expose those interfaces. The software stack and tool chain is fully in the control of the organisations that develop the services, so it's not a material concern for my question. As I say, if someone from the maintainers team can give me a steer here, it would help greatly. |
|
From clause 1 of the v2 spec:
You have made it clear that you provide an API for your clients to implement. You should version that API, why not use SemVer? Only reason I can think of is if client X's implementation is not compatible with client Y's implementation, in which case, what value do you even provide for them? |
|
Skimming through the OpenAPI propaganda once again, I found this bit on what they define an API is:
@eibhear-from-athlone, can you provide any technical reasons why your product should not fall under the definition of an API? That description sounds like a particular kind of software known as an API. The whole point of the OpenAPI initiative is to separate the definition of the interfaces from their implementations. I don't see how that separation can be managed in the real world, if both must have the same version numbers. Maybe there is an existing convention in your particular market that implies something else? My simple understanding of the model is something like: It seems to me that the consumer and the service probably need to agree on which version of the API spec that they are referencing, much like some package managers reference SemVer 1.0.0-beta and other reference 2.0.0. Without more detailed context, all any of us can do is quote the spec, apply some common sense and add that context matters, so lacking that, you're not likely to get a more definitive answer. Not even from one of the maintainers, who are likely busy providing value for their employers or just trying to live a life. My intuition tells me that SemVer is agnostic in your particular domain. Apply it to the service and its exposed API's as they co-evolve or apply to each of the components separately. How you should apply to satisfy your needs and those of your clients, is entirely up to you. |
|
On 2023-06-20 Joseph Donahue ***@***.***> wrote:
> An Application Programming Interface (API) defines the allowed interactions
> between two pieces of software, just like a User Interface defines the ways
> in which a user can interact with a program.
That description sounds like a particular kind of software known as an API.
I cannot see how you can interpret this as descibing a "software" at all. It describes [part of] the behavior of some software pertaining to the API part, but not the software itself. As I see it the software _implements_ an API, but it _is not_ an API.
The whole point of the OpenAPI initiative is to separate the definition of the
interfaces from their implementations. I don't see how that separation can
be managed in the real world, if both must have the same version numbers.
It is quite common for software to implement (or "provide") more than one API, and sometimes even multiple versions of the same API. A common example is the way COM object servers can serve multiple Interfaces (e.g. for backward compatibility) in the Windows and CLI/CLR world. An API descibing this interaction would typically also evolve into several corresponding versions as the collection of interfaces and their versions evolves over time. A web-based API isn't much different in this regard.
A similar situation is where a piece of software allows for plugin modules. It may not implement any actual plugin itself, but it declares the API and also problably is capable of using it (i.e., "be a client" of it, or to "call it").
Therefore, I cannot see how software can use SemVer at all unless the versioning considers collectively the compatibility of _all_ the APIs it provides or documents.
My intuition tells me that SemVer is agnostic in your particular domain.
Apply it to the service and its exposed API's as they co-evolve or apply
to each of the components separately.
I would also like to interpret it like that, and it makes a lot of common sense! But, alas, as I too understand the SemVer spec this is not what it currently describes. Furthermore, software that don't provide an API (very common for classical Windows apps with only a UI, for example) cannot be versioned using SemVer in any compliant way; they must be versioned in some other way although it may of course incidentally resemble the SemVer principles in the remaining aspects.
…--
Ben Hetland ***@***.***>
|
LOL, you tell that to the thousands of test engineers who write tests for those UI's, including robotics systems that work it through the touch interface. That is an absurd statement that has been put to rest as false here on multiple occasions. I've even had talks with groups who wanted to use it to version documents. At least one of them has written an overlay spec that describes how to correctly apply full SemVer semantics and syntax in documents. The SemVer spec literally says that you define what the API is, so you could pretty much declare chisel marks in a stone artifact as the "API" and apply SemVer thereon, if you really wanted to take it to the extreme: Statue 2.0.0, changes since 1.1350.1: 2 new cracks have been introduced as a result of recent refinements :)
How do you declare your API's? YAML, XML, JSON, signal flags? Sounds like software to me. An API MAY define behavior or any other aspect of the software you wish to call the API. The fact that some implementations support multiple API's just drives my point home really. If you introduce a breaking change in the way one API is implemented and not the others, are you really going advertise a breaking change to all of them? I hope not. An earlier version of me was a tester on the Windows kernel team, before they fired all the testers, I owned a small bit of RPC, all of MIDL, Task Scheduler and Service Manager. We versioned interfaces separately from the implementation. Every day we built several thousand different versions of the client and server implementations (lots of branches), mostly without having to bump any interface versions. RPC/COM interface versioning even uses a similar semantic scheme to SemVer. I don't recall the details today, as I have gone through several breaking changes myself, since then, but I think we were actually versioning the interfaces in header files back then. If your interface definitions are embedded in some way in your implementation code and you don't have the desire or resources to fix that problem, that's fine with me. I am never going to buy the argument that SemVer cannot be applied to API's independently of implementations. I have done it, and it's a common practice. |
|
@bhetland does your current versioning scheme convey any semantic content? Would the SemVer syntax and semantics be useful to your team and your customers? If the answer to the first is no and yes to the second, then don't let anybody's dogmatic misread of the SemVer spec stop you from doing whatever makes the most sense. Call it a SemVer inspired semantic version scheme for OpenAPI's and move on. But don't let the idea that SemVer could be used, prevent you from innovating either. |
and others
Where I work we define APIs that are to be implemented by independent organisations. As the APIs are independent of the implementing software, we apply indepdendent versioning to them (in the case of our OpenAPI documents, for example, the
info.versionattribute describes the version of the API, and not necessarily the service behind the interface).We are considering mandating SemVer on the APIs. However, feedback we have received is that SemVer can't be applied directly, as SemVer (at 2.0.0 at the time of writing) applies to the software that declares the API.
We are left with one of the following options:
We declare internally that we are using something like (or inspired by) SemVer, but we can't tell people that SemVer – as described at https://semver.org/ – applies, because SemVer applies to the software only.
We get confirmation from that SemVer maintainers that SemVer can be applied to APIs independently. For certainty, I could proceed to raise a PR (perhaps an RFC is required) to add this confirmation to the FAQ in semver.md.
If the SemVer maintainers believes that 2.0.0 of SemVer means that SemVer can only be applied to the software, I could then raise an RFC to replace the text
with the following (or something like it)
If the RFC is not accepted (i.e. "closed" in the terms of CONTRIBUTING.md), I will have to revert to my clunky option 1. above.
Can you advise whether my clunky option 1. is all I can use? or that the current SemVer specification can be assumed to include independent versioning of APIs? or if I could/should raise an RFC for your consideration?
The text was updated successfully, but these errors were encountered: