The problem is that we went backwards in many ways...
REST made it easier to define the API and to understand, but pretty much impossible to autogenerate a client for example.
With a well made SOAP API you can autogenerate client code for it, that is type safe and self-documented almost.
For example after using cxf to autogenerate Java for a given SOAP API I may be able to then write in my app:
SampleApiRecord record = new SampleApiRecord();
try {
record.authenticate(token);
} catch (AuthenticationException e) {
// auth failed
}
User user = record.getUserData();