В моей команде есть несколько ex-google инженеров. От них я узнал, что у Гугла есть публичные (!) гайдлайны по дизайну API. Называется «Google AIPs: API Improvement Proposals»

👉 https://google.aip.dev/

Вот несколько примеров документов:

AIP-193: Errors — формат ошибок, куда писать код ошибки, куда сообщение, локализацию, и как передать доп. информацию.

AIP-234: Batch methods: Update — батчевые ручки. Что должны отвечать синхронные и асинхронные апдейты и как сигнализировать, что только часть данных обновилась успешно. Отдельный поинт что батчевые ручки (и вообще кастомные операции) называются через двоеточие, типа
/users:batchUpdate

AIP-164: Soft delete — удаление и восстановление, в каких API-методах удалённые сущности могут и не могут появляться, и как же их всё-таки получить. И что делать, если восстановление долгое.

Там есть пропозалы и по клиентам для этих API. Короче, интересный справочник!