There are a lot of APIs exposed by Salesforce, like Bulk APIs, Composite APIs, SOAP APIs. But I read that it is better to use REST APIs than SOAP one. Which is fine, but has anyone came across any requirement or use case where using an SOAP API is imperative.
Any examples, document reference, would be helpful.
As the other answers mentioned, it mostly comes down to which works well with the language/system you are calling from.
However, you asked for a specific example where the SOAP API showed its true superiority over the REST API!
Joking - use the right tool for the job!
It's important to consider the types of call you will be making against the APIs. For instance, I recently ran into a scenario with a dozen or so dirty records that needed to be updated - Choose Your Own Adventure - Dirty Dozen showdown with the REST API vs SOAP API vs BULK API.
Long story short, the REST API (as it was at the time), was super inefficient at doing what was a trivial call with the SOAP API. The Bulk API was another option, but there was a lot of ceremony to get it going.
That said, Salesforce is actively refining the APIs all the time. They will likely close the gap between the APIs in the future (forward looking statement blah-de-blah).
Another quick example of when you might use the SOAP API over the REST API - direct login with a stored user name and password. This isn't such a great example anymore as there are other authentication options available such as the OAuth flows.
TL;DR: Use the API that aligns best with the system/language you are invoking it from. Beyond that, consider the actions you want to perform against the API. They all have their strengths and weaknesses.
See also:
Typically, the language or system's features will determine which API to use. REST tends to work better in dynamic languages, like JavaScript, while SOAP tends to work best in strongly typed languages, like Java. Some systems have no support at all for REST APIs, and therefore require SOAP. Other languages have specialized libraries or tools that make one API or other preferable.
One specific example that I seem to recall is that some versions of Oracle's PL/SQL only supported Web Service calls, and therefore you had to use the SOAP API. There's rarely any time where you're forced to use one over the other, but it's often true that one API or the other will greatly reduce development time and costs. Any language or platform with strong WSDL support and weak REST support will benefit from using the SOAP API, if only because it'll reduce time to deployment.
You can go through API Basics to understand different kinds of API that salesforce works.
Which API Do I Use?
Choosing the right API for your integration needs is an important decision. Here’s some information on our most commonly used APIs, including supported protocols, data formats, communication paradigms, and use cases. Treat this section as a reference you can return to when you’re considering which API to use.
soap Works over with HTTP, HTTPS, SMTP, XMPP but rest works over with HTTP and https only.
Typically, the REST API operates on smaller numbers of records. You can GET a single record using its URL and you can also run a query and bring back a set of records that match that query.
SOAP is good for applications that require formal contracts between the API and consumer since it can enforce the use of formal contracts by using WSDL (Web Services Description Language). Additionally, SOAP has built-in WS-Reliable messaging to increase security in asynchronous execution and processing. Finally, SOAP has built-in stateful operations. REST is naturally stateless, but SOAP is designed to support conversational state management.
