This is primarily to try and learn from, I should've made this a bit clearer.

I manage 40% of a major enterprise API effort for the government. At work we use RAML to design and specify our APIs and they are all REST. The actual API requirements come from existing data systems or external teams.

For my personal software I design all my APIs as JSON objects, using TypeScript interfaces for their definitions, and I associate those objects to a service name. So data will look like a parent object with properties data and service where data is the defined JSON payload and service is the name of that data schema. This allows me to use a WebSocket connection for all my various services and it’s so much faster.

This was shared on HN over a decade ago, but still stands the test of time: http://ciar.org/ttk/public/apigee.web_api.pdf