[GH-ISSUE #453] What is exactly an API? #6319

New Issue

GiteaMirror · 2026-06-17T05:03:19-05:00

GiteaMirror commented

2026-06-17 05:03:19 -05:00

Originally created by @machitgarha on GitHub (Jul 29, 2018).
Original GitHub issue: https://github.com/semver/semver/issues/453

I know a subjective definition of API, but I don't understand what an API exactly is. It may have many different definitions in various projects. However, I don't know if it is an issue or not. I'm submitting this issue because there's no exact definition on SemVer for API.

Let me say using examples; what is an API:

If you are building an app (e.g. for Android)? Does it refer to helps for users how they use the app, even if the whole app has a wonderful GUI and everything is clear for every user?
If you are developing a web project (e.g. a website)? Does it mean a complete guide for users?
If you are developing something with very limited users and they know whole project?

Shouldn't an API definition exist?
Thanks.

Originally created by @machitgarha on GitHub (Jul 29, 2018). Original GitHub issue: https://github.com/semver/semver/issues/453 I know a subjective definition of API, but I don't understand what an API exactly is. It may have many different definitions in various projects. However, I don't know if it is an issue or not. I'm submitting this issue because there's no exact definition on SemVer for API. Let me say using examples; what is an API: 1. If you are building an app (e.g. for Android)? Does it refer to helps for users how they use the app, even if the whole app has a wonderful GUI and everything is clear for every user? 2. If you are developing a web project (e.g. a website)? Does it mean a complete guide for users? 3. If you are developing something with very limited users and they know whole project? Shouldn't an API definition exist? Thanks.

GiteaMirror closed this issue

2026-06-17 05:03:19 -05:00

GiteaMirror commented

2026-06-17 05:03:20 -05:00

@jjonas3 commented on GitHub (Jul 30, 2018):

An API is a piece of software's interface to the rest of the world. Wikipedia has a decent definition.
https://en.wikipedia.org/wiki/Application_programming_interface

@jjonas3 commented on GitHub (Jul 30, 2018): An API is a piece of software's interface to the rest of the world. Wikipedia has a decent definition. https://en.wikipedia.org/wiki/Application_programming_interface

GiteaMirror commented

2026-06-17 05:03:21 -05:00

@machitgarha commented on GitHub (Aug 2, 2018):

@jjonas3
Thanks for the link. However, could you explain about examples I wrote in my question?
Besides, the whole SemVer rules are based on API, but it lacks the definition of API! I think it's a big fault. Even if the definition of API was a well-known one, at least, SemVer must have a general/subjective definition of API.

@machitgarha commented on GitHub (Aug 2, 2018): @jjonas3 Thanks for the link. However, could you explain about examples I wrote in my question? Besides, the whole SemVer rules are based on API, but it lacks the definition of API! I think it's a big fault. Even if the definition of API was a well-known one, at least, SemVer must have a general/subjective definition of API.

GiteaMirror commented

2026-06-17 05:03:21 -05:00

@grv87 commented on GitHub (Aug 12, 2018):

SemVer leaves API to be defined by the project implementing it.
But SemVer FAQ could have contained some examples/guidelines.

For website, I would consider API as a set of pages (links) that are browseable by a visitor. If you remove a page completely, without redirect, then the visitor would get 404, and this is breaking change.
But I can't imagine why would you need to version website.

For 1 and 3, clear and known by users are not criteria used by SemVer. There is no difference how many users you have or how well they know your work.
For an app, I think that API includes menus, toolbars, hotkeys and all other interactive GUI elements. E.g. if you had a clickable page title with popup menu and then made it non-clickable then it is breaking API change.

@grv87 commented on GitHub (Aug 12, 2018): SemVer leaves API to be defined by the project implementing it. But SemVer FAQ could have contained some examples/guidelines. For website, I would consider API as a set of pages (links) that are browseable by a visitor. If you remove a page completely, without redirect, then the visitor would get 404, and this is breaking change. But I can't imagine why would you need to version website. For 1 and 3, `clear` and `known by users` are not criteria used by SemVer. There is no difference how many users you have or how well they know your work. For an app, I think that API includes menus, toolbars, hotkeys and all other interactive GUI elements. E.g. if you had a clickable page title with popup menu and then made it non-clickable then it is breaking API change.

GiteaMirror commented

2026-06-17 05:03:21 -05:00

@machitgarha commented on GitHub (Aug 15, 2018):

@grv87

First, take a look at this: https://softwareengineering.stackexchange.com/questions/18720/

From your saying, SemVer documentation should either mention "We leave API definition to the project implementing it.", or have some basic rules around API definitions, even by referring to somewhere. If it was defined, this thread didn't exist. A documentation should be accurate.

Finally, in the specifications we see (no. 1):
"Software using Semantic Versioning MUST declare a public API. This API could be declared in the code itself or exist strictly in documentation. However it is done, it should be precise and comprehensive."
We can't get from the bold text that an API could be GUI. Even if we can, what about the terms of "precise" and "comprehensive"? Can a GUI be precise?

@machitgarha commented on GitHub (Aug 15, 2018): @grv87 First, take a look at this: https://softwareengineering.stackexchange.com/questions/18720/ From your saying, SemVer documentation should either mention "We leave API definition to the project implementing it.", or have some basic rules around API definitions, even by referring to somewhere. If it was defined, this thread didn't exist. A documentation should be accurate. Finally, in the specifications we see (no. 1): "Software using Semantic Versioning MUST declare a public API. **This API could be declared in the code itself or exist strictly in documentation.** However it is done, it should be precise and comprehensive." We can't get from the bold text that an API could be GUI. Even if we can, what about the terms of "precise" and "comprehensive"? Can a GUI be precise?

GiteaMirror commented

2026-06-17 05:03:22 -05:00

@grv87 commented on GitHub (Aug 17, 2018):

I considered that website is a set of pages, and web application ≠ web site.

For web applications situation is, of course, different. For e.g. REST applications there are even tools for detecting API changes, so I assumed they are out of this question. And rich web applications could be considered the same way as GUI application.

@MAChitgarha, you wrote:

SemVer documentation should either mention...

and then quoted specification:

Software using Semantic Versioning MUST declare a public API

Doesn't this quote say what I said: that API definition is left for the implementing project?

On GUI: I can't get from that bold text that API couldn't be GUI.

Maybe some words are missing from specification. Precise should be the definition, not the API itself.
I don´t think that preciseness is even applicable to API.

Definition is precise if you define it right. For example, pixels and points of GUI elements (for most circumstances) couldn't be guaranteed so definition in these terms would be imprecise. But definition of behavior of menu items, their relative order and so on would be precise.

Definition of public API is necessary only to determine what is an incompatible change and what is not.
Recently I proposed another definition for incompatible change that doesn't depend on public API definition, here: https://github.com/semver/semver/pull/452#issuecomment-412378851:

Incompatible change means that user of the product that used it correctly before cannot replace old version with the new one without any changes to his code or behavior

With this new definition we could get rid of public API definition, so this question would not occur. But an author of the project still should define what he considers incompatible changes and what not.
What do you think?

@grv87 commented on GitHub (Aug 17, 2018): I considered that website is a set of pages, and web application ≠ web site. For web applications situation is, of course, different. For e.g. REST applications there are even tools for detecting API changes, so I assumed they are out of this question. And rich web applications could be considered the same way as GUI application. @MAChitgarha, you wrote: > SemVer documentation should either mention... and then quoted specification: > Software using Semantic Versioning MUST declare a public API Doesn't this quote say what I said: that API definition is left for the implementing project? On GUI: I can't get from that bold text that API *couldn't* be GUI. Maybe some words are missing from specification. Precise should be the definition, not the API itself. I don´t think that preciseness is even applicable to API. Definition is precise if you define it right. For example, pixels and points of GUI elements (for most circumstances) couldn't be guaranteed so definition in these terms would be imprecise. But definition of behavior of menu items, their relative order and so on would be precise. Definition of public API is necessary only to determine what is an incompatible change and what is not. Recently I proposed another definition for incompatible change that doesn't depend on public API definition, here: https://github.com/semver/semver/pull/452#issuecomment-412378851: > Incompatible change means that user of the product that used it correctly before cannot replace old version with the new one without any changes to his code or behavior With this new definition we could get rid of public API definition, so this question would not occur. But an author of the project still should define what he considers incompatible changes and what not. What do you think?

GiteaMirror commented

2026-06-17 05:03:23 -05:00

@machitgarha commented on GitHub (Aug 17, 2018):

@jjonas3

However, I think websites should be versioned too, because of such general benefits as returning to a previous version or working on a project as a team member. I would recommend this. BTW, every man has his own opinion.

And about the quoted spec, I agree, it exists; but is dumb. What I'm saying is "A document should be accurate, with detailed descriptions to prevent misunderstood". More accurate, more improvement chances. Do you agree?

Maybe some words are missing from specification. Precise should be the definition, not the API itself.
I don´t think that preciseness is even applicable to API.

Good point. I agree with you. However, the SemVer documentation is precise, and missing in a few specifications.

Also, the rest of your saying is almost true. But can we say "in the code itself" means a GUI? Doesn't it mean declaring by comments? In my opinion, in the code should be by the code. What's your idea?

@machitgarha commented on GitHub (Aug 17, 2018): @jjonas3 However, I think websites should be versioned too, because of such general benefits as returning to a previous version or working on a project as a team member. I would recommend this. BTW, every man has his own opinion. And about the quoted spec, I agree, it exists; but is dumb. What I'm saying is "A document should be accurate, with detailed descriptions to prevent misunderstood". More accurate, more improvement chances. Do you agree? > Maybe some words are missing from specification. Precise should be the definition, not the API itself. I don´t think that preciseness is even applicable to API. Good point. I agree with you. However, the SemVer documentation is precise, and missing in a few specifications. Also, the rest of your saying is almost true. But can we say "in the code itself" means a GUI? Doesn't it mean declaring by comments? In my opinion, _in the code_ should be _by the code_. What's your idea?

GiteaMirror commented

2026-06-17 05:03:23 -05:00

@jwdonahue commented on GitHub (Aug 18, 2018):

Application Programming Interface seems quite clear to me. The spec even states that it's your responsibility to define what you mean by it. It's just a label used in the spec to reference a loosely defined concept. You are asking for precision where accuracy is sufficient. The more precise the spec, the less useful it becomes. Accuracy does not require precision. If +/- 500 meters is sufficient for my purposes, I should not carry around any more decimal places than are required to specify which kilometer I am referring to. In fact, adding artificial precision is less accurate if I only have a kilometer long chain to measure with.

It's pointless to have millimeter precision when one is discussing the distances between the stars in the universe. The spec is just precise enough, to be useful for its intended purpose. There are some who prefer less precision in order to expand its usefulness into areas @mojombo had no interest in covering.

@MAChitgarha, unless you have further questions or intend to issue a PR with specific changes to the spec, please close this thread at your earliest possible convenience.

@jwdonahue commented on GitHub (Aug 18, 2018): Application Programming Interface seems quite clear to me. The spec even states that it's your responsibility to define what you mean by it. It's just a label used in the spec to reference a loosely defined concept. You are asking for precision where accuracy is sufficient. The more precise the spec, the less useful it becomes. Accuracy does not require precision. If +/- 500 meters is sufficient for my purposes, I should not carry around any more decimal places than are required to specify which kilometer I am referring to. In fact, adding artificial precision is less accurate if I only have a kilometer long chain to measure with. It's pointless to have millimeter precision when one is discussing the distances between the stars in the universe. The spec is just precise enough, to be useful for its intended purpose. There are some who prefer less precision in order to expand its usefulness into areas @mojombo had no interest in covering. @MAChitgarha, unless you have further questions or intend to issue a PR with specific changes to the spec, please close this thread at your earliest possible convenience.

GiteaMirror commented

2026-06-17 05:03:24 -05:00

@machitgarha commented on GitHub (Aug 19, 2018):

I think this misunderstanding (accuracy and precise) is related to my writing. Sorry, but I don't know what's the differences between precise and accurate in English language. So, I used them interchangeably.

Thanks to @grv87, I got the answers of almost all of my questions. But just one issue remains for me that I'm going to create a new thread for that. Thank you all.

EDIT: The new issue is #459. Thank you for paying attention.

@machitgarha commented on GitHub (Aug 19, 2018): I think this misunderstanding (accuracy and precise) is related to my writing. Sorry, but I don't know what's the differences between precise and accurate in English language. So, I used them interchangeably. Thanks to @grv87, I got the answers of almost all of my questions. But just one issue remains for me that I'm going to create a new thread for that. Thank you all. __EDIT__: The new issue is #459. Thank you for paying attention.

GiteaMirror commented

2026-06-17 05:03:25 -05:00

@jwdonahue commented on GitHub (Oct 9, 2018):

Reference #468 for tracking.

@jwdonahue commented on GitHub (Oct 9, 2018): Reference #468 for tracking.

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/semver#6319