Ensure consistency when using either Application or API terms

[smoya]

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

[timmiedinnie]

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 #950 for review purposes only. In my opinion, using the term "API" consistently would be a better approach.

[smoya]

To the rest of codeowners @fmvilas @derberg @dalelane @char0n: do you think this makes sense?

[sagnik3788]

hello @smoya can you assign me any issue so that i can work on docs

[smoya]

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 #950 @timmiedinnie ? Do you think it is worth still?

[smoya]

With your 👍 reaction, I understand you @timmiedinnie are gonna work on the suggested change.
I closed #950 in favour of that new PR you will create.

Thank you so much! 🙌

[akkshitgupta]

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

[helios2003]

Is this issue still relevant?

[smoya]

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.

[helios2003]

Yes, in my PR I tried to take care of it. Can you please review it? @smoya

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity 😴

It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation.

There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model.

Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here.

Thank you for your patience ❤️

[xopino]

Hello everyone! 👋

I’m new to the discussion and have been following along with interest. I’ve also been a bit confused by the term "application" 🤔. It seems to be used in different ways—sometimes referring to a schema in the spec (See: definitionsApplication), and other times to the spec itself as an application (See introduction).

For those of us working on multiple applications using this spec, it would be super helpful to have consistency in this term.

The term "Application API" makes sense to me as it clearly refers to "the API of an application," avoiding the potential confusion that "API" alone could cause—where it might be interpreted as a single API serving multiple applications.

I hope this helps 😊