REST API удобно проектировать не от контроллеров, а от сценариев пользователя и состояния доменной модели.
Ресурсы
Хороший ресурс имеет понятную ответственность. Если endpoint начинает отвечать за несколько разных сценариев, стоит проверить модель и границы API.
Ошибки
Ошибки должны помогать клиенту исправить запрос. Для этого полезны стабильные коды, человекочитаемые сообщения и поле с деталями.
Документация
OpenAPI-документация должна быть частью разработки, а не отдельным артефактом после релиза.