API deprecation comes in two flavors: internal and external. Internal APIs are APIs used by components that are fully controlled by you and your team or organization. You can be sure that all API users will upgrade to the new API within a short time. External APIs are used by users or services outside your direct sphere of influence. There are a few gray-area situations where you work for a huge organization (think Google), and even internal APIs may need to be treated as external APIs. If you're lucky, all your external APIs are used by self-updating applications or through a web interface which you control. In those cases, the API is practically hidden, and you don't even need to publish it.

If you have a lot of users (or a few very important users) using your API, you should consider deprecation very carefully. Deprecating an API means that you force your users to change their application to work with you or stay locked to an earlier version.

There are a few ways you can mitigate the pain:

• Don't deprecate. Extend the existing API or keep the previous API active. It is sometimes pretty simple although it adds testing burden.
• Provide client libraries in all relevant programming languages to your target audience. This is always a good practice. It allows you to make many changes to the underlying API without disrupting users (as long as you keep the programming language interface stable).
• If you have to deprecate, explain why, allow ample time for users to upgrade and provide as much support as possible (for example, an upgrade guide with examples). Your users will appreciate it.