День 2288. #ЗаметкиНаПолях
5 Основных Ошибок при Создании API. Продолжение
Начало

3. Вводящие в заблуждение или неверные коды состояния
Ошибка: Возврат 200 OK для всего — даже когда что-то не так.
Реальность: Коды состояния HTTP существуют по определенной причине: для передачи намерения.
Плохо:

return Results.Ok("User not found.");

Проблема: Клиент видит 200 OK. Но пользователя не существует. Это сбивает с толку! Теперь клиенту нужно разобрать строку сообщения, чтобы понять, что не так. Это плохая практика.
Лучше:

var user = await db.Users.FindAsync(id);
if (user is null)
  return Results.NotFound(
   $"Пользователь с id={id} не найден.");

return Results.Ok(user);

Используйте:
- 400 BadRequest → Плохие входные данные
- 401 Unauthorized → Необходим вход в систему
- 403 Forbidden → Доступ запрещён (нет прав)
- 404 Not Found → Ресурс не найден
- 500 Internal Server Error → Что-то сломалось на сервере.

Почему важно:
- Клиенты могут реагировать программно (повторять запрос, перенаправлять пользователя, показывать ошибку и т.д.).
- Ваш API ведёт себя как добропорядочный гражданин в Интернете.

4. Лишние данные в моделях ответа
Ошибка: Возврат целых сущностей БД или гигантских вложенных моделей.
Реальность: Клиентам обычно нужен небольшой фрагмент данных, а не вся схема вашей БД.
Плохо:

app.MapGet("/orders", async (DbContext db) =>
{
  var orders = await db.Orders.ToListAsync();
  return Results.Ok(orders);
});

Проблемы:
- Утечка внутренней структуры БД.
- Может случайно раскрыть конфиденциальные поля.
- Большая нагрузка на трафик = медленный API.

Лучше:

app.MapGet("/orders", async (DbContext db) =>
{
  var orders = await db.Orders
    .Select(o => new
    {
      o.Id,
      o.CustomerName,
      o.TotalAmount,
      o.OrderDate
    })
    .ToListAsync();

  return Results.Ok(orders);
});

Почему важно:
- Вы контролируете, какие именно данные покидают ваш сервер.
- Меньше и быстрее ответы = более довольные пользователи и лучше SEO.
- Меньше риска безопасности, если ваша модель изменится позже.

Окончание следует…

Источник: https://thecodeman.net/posts/building-apis-top-5-mistakes