[flywheel]

Removing APIs is not a great practice though. Look at AWS, they version their APIs, they don't just remove them, and removing them should be unnecessary if your underlying tech isn't brittle and badly written. "Depreciated" is a far better term to use, with a far better outcome in my opinion. Companies that remove old versions of APIs and break existing client apps (that possibly can't be udpated) really suck.

[hamburglar]

1) Whether you agree with the practice doesn't affect the terminology used. People remove APIs. Before doing that, they deprecate them for a period to advise people to move off of them.

2) If you were to always maintain backward compatibility, how is "depreciated" in any way an accurate term? If the old API continues to work indefinitely, its value stays the same.

[smichel17]

I don't think these two are incompatible?

If APIv3 has a `/foo` endpoint that is deprecated, usually I take that to mean that the developers discourage its use, and likely plan to remove it in a future version (say, APIv4 or APIv5). `/foo` will never be removed from APIv3, because that would be a breaking change, and so if I'm willing to stay on v3 forever, that's fine, but in the (likely) event I will want to take advantage of new features at some point in the future, I'm doing myself a disservice by using /foo because it will make the migration harder.

There is at least one case where I think "deprecated" is clearly, inarguably, the right word: when the developer wants to remove a part of an API (say, because it is a large maintenance burden), but it's also committed to stability, so they won't remove that api until some acceptably small number of users are using it.

[TallGuyShort]

Right, you version APIs and have a policy of deprecated APIs being removed in the next version. Or you can just copy and paste a comment calling people shitheads for politely disagreeing with you. Your call.

[oceanswave]

The “public APIs form an immutable, irrevocable contract” argument means that an api layer with these tenants is always going to be a source of technical debt. Get it right the first time or fight an ever growing compatibility matainance war - even when your instrumentation is saying that old apis aren’t being used, just published, seems like a footgun