spec
spec copied to clipboard
asyncapi
Ensure consistency when using either `Application` or `API` terms
Description
Current spec (and also v3) mixes the terms Application and API (and derivatives) to refer to the same thing.
For example, some of the Info Object fields say:
title: The title of the application. version: Provides the version of the application API. description: A short description of the application. contact: The contact information for the exposed API.
By taking the following statement that can be found in the Introduction:
The AsyncAPI Specification defines a set of files required to describe the API of an application.
I vote for unifying these under one term to avoid any possible confusion. I believe we should stick with the Application API term.
cc @derberg @jonaslagoni @alequetzalli @dalelane @fmvilas
As stated in my PR:
I agree there should be a change in favor of consistency.
However the suggestion to replace "Application" with "Application API" may not be suitable in most contexts. The resulting phrase, "The Application's Application programming interface," could be confusing or redundant.
In this proposed change, only a few instances of "Application" were replaced with "Application API," and it may not be appropriate in all situations. Furthermore, replacing "API" with "Application API" often creates even more awkward phrasing.
Therefore, I have submitted https://github.com/asyncapi/spec/pull/950 for review purposes only. In my opinion, using the term "API" consistently would be a better approach.
To the rest of codeowners @fmvilas @derberg @dalelane @char0n: do you think this makes sense?
Therefore, I have submitted #950 for review purposes only. In my opinion, using the term "API" consistently would be a better approach.
Sorry for not coming back to this earlier, but I noticed I never shared I also agree, after reviewing your PR, that the simple term "API" could fit better. And again, it might happen not all cases are swappable.
Would you be happy to work on that and close https://github.com/asyncapi/spec/pull/950 @timmiedinnie ? Do you think it is worth still?
With your 👍 reaction, I understand you @timmiedinnie are gonna work on the suggested change. I closed https://github.com/asyncapi/spec/pull/950 in favour of that new PR you will create.
Thank you so much! 🙌
I have gone through the discussion and understood well. If no one is working on it I would love to create a Pull Request on the same
Is this issue still relevant?
I believe it is. But consider the discussion that happened in this issue and how it does not make sense to just replace all terms in favour of "API". There are cases that make sense, others not. That's the real work this issue is about, to find when it does make sense.
Yes, in my PR I tried to take care of it. Can you please review it? @smoya