Какой подход и инструменты вы используете для проектирования ответов endpoint?

А, проектирование API, говоришь? Ну, это ж святое дело, ёпта. Слушай, я тебе как человек, который уже на этом собаку съел (и не одну), расскажу, как я это обычно делаю, чтобы потом не было мучительно больно за каждый запрос.

1. Про обёртку для ответов — это священная корова. Вот смотри, если ты каждый раз возвращаешь данные в разном формате — это пиздец, чувак. Фронтендеры тебя живьём сожрут. Поэтому я всегда заворачиваю всё в единую структуру. Успех — так, ошибка — эдак. В Symfony, например, можно наколдовать DTO или нормализатор, чтобы не писать одно и то же по сто раз.

// Когда всё ок — вот такую радость отдаём
{
  "status": "success",
  "data": { /* тут основная мякоть, ради которой всё и затевалось */ },
  "meta": { /* а тут уже пагинация, тайминги, всякая служебная хрень */ }
}

// А когда клиент накосячил — бьём по рукам вот таким ответом
{
  "status": "error",
  "code": "VALIDATION_FAILED",
  "message": "Ну ты чё, мужик, данные-то кривые прислал",
  "details": [ /* а тут уже по полям разбор полётов, где именно он обосрался */ ]
}

2. HTTP-статусы — это не просто цифры, это язык общения. Тут доверия ебать ноль, если ты 404 будешь отдавать когда у клиента валидация не прошла. Запомни раз и навсегда:

• 200 OK — всё гуд, держи свои данные (GET, PUT, PATCH).
• 201 Created — только что для тебя чё-то родил, вот тебе его адресок (после успешного POST).
• 204 No Content — удалил твоё горе, даже отвечать нечего (успешный DELETE).
• 400 Bad Request — ты, дружок, прислал какую-то дичь, исправляй (ошибка валидации).
• 404 Not Found — искал, искал, нихуя не нашёл.
• 429 Too Many Requests — ой, полегче, задолбал уже запросами, иди поспи.

3. Инструменты — наш бронежилет от говнокода.

• Symfony: SymfonyComponentSerializer — это наш сериализатор-тяжеловес. FOSRestBundle или api-platform — чтобы не изобретать велосипед для каждой ручки. Особенно api-platform — он тебе и документацию натянет, и кучу рутинной работы сделает.
• Документация: Без неё — пиши пропало. Всегда, блядь, всегда описываю схему ответов через OpenAPI/Swagger. В мире Symfony для этого есть nelmio/api-doc-bundle — вещь просто овердохуища.

  # Вот смотри, как это примерно выглядит в коде
  /**
  * @OAResponse(
  *     response=200,
  *     description="Вот тебе юзер, доволен?",
  *     @OAJsonContent(
  *         type="object",
  *         @OAProperty(property="status", type="string", example="success"),
  *         @OAProperty(property="data", ref=@Model(type=User::class))
  *     )
  * )
  */

4. А теперь практические фишки, без которых — никуда.

• Заголовок Content-Type: application/json — это как штаны перед выходом на улицу. Без него — голый и стыдно.
• Пагинация для коллекций — это обязательно. Использую Pagerfanta или что-то подобное. В meta кидаю total, page, per_page, чтобы фронт знал, что к чему.
• DTO (Data Transfer Objects) — это мой главный козырь против ебли с сущностями Doctrine. Не сериализую сущности на прямую, а маппю в DTO. Так и поля лишние не светятся, и проблем с N+1 или циклическими ссылками нет. Чистая магия.
• Для дебага (только на staging/dev, епта!) можно в ответ сунуть время выполнения или request id. Потом по логам как по маслу всё ищется. Но на проде эту отладочную хуйню — нахуй.

Вот такой подход, чувак. Предсказуемо, надёжно, и фронтендеры тебе спасибо скажут, а не будут каждый раз гадать, что ты им в этот раз подсунул.