One general thing to remember is that there will normally be multiple levels of API, from data to domain to business to application. The APIs at those levels are likely to be designed based on different design principles, e.g.:
data level - API will be typically CRUD and query operations, data correspond to the information model of the served resource
domain level - API will be typically industry standard concepts, e.g. medication list transactions
business level - API will be transactional, around processes specific to the enterprise, e.g. admission procedures
application / presentation - APIs might exist at this level to provide user-level interactions (workflow) with data or business processes.
An application might be written to talk to one or more such APIs, so its view of things will depend on those APIs.
We don't write API's as learning material for newbies, but for professional communication, so that is no problem.
Also for the rest I agree.
There is need for API's for interaction between two OpenEhr environments, and API's for the rest of communications (that will be used most). I mentioned FHIR as example, of course FHIR is not perfect. But we cannot deny its success.
A specific message-format-API is not what I am looking for, by combining several API's, a developer should be able to craft any message he wants, very easy. I have done that a lot, also last year. It is sometimes my daily income.
Often we forget that on discussion-lists we are in the year 2525, but on the market we still see message types from 20 years ago, HL7v2, EDIFACT, XML, vendor specific formats, it all happens a lot. Sometimes the only way to communicate with some critical software-products.