Коды состояния HTTP - 404 / NotFound против 204 / NoContent против 200 / Ok

Question

У меня есть объекты виджетов, которые принадлежат объектам компании. Между компаниями и виджетами существует отношение один ко многим.

Вот мой первый проход по методу Get:

[Route("MyApi/Companies/{companyId}/WidgetAdministration/[controller]")]
[HttpGet]
public async Task<ActionResult<List<WidgetDTO>>> GetWidgets([FromRoute] int companyId)
{
    // get company
    var company = await _xyvidContext.Companies
        .Where(c => c.CompanyId == companyId)
        .AsNoTracking()
        .Include(c => c.Widgets)
        .FirstOrDefaultAsync();

    if (company == null)
    {
        return NotFound();
    }

    // get corresponding Widgets
    List<WidgetDTO> widgetDtos = company.Widgets
        .AsQueryable()
        .ProjectTo<WidgetDTO>(_mapper.ConfigurationProvider)
        .ToList();

    if (widgetDtos == null)
    {
        return StatusCode(Microsoft.AspNetCore.Http.StatusCodes.Status500InternalServerError);
    }
    else if (widgetDtos.Count == 0)
    {
        return NoContent();
    }
    else
    {
        return Ok(widgetDtos);
    }
}

Очевидно, что если компания не найдена, он был удален или никогда не существовал, я должен вернуть 404 / NotFound, Correct?

Если я прошу просмотреть все виджеты, принадлежащие компании 1, но у компании 1 нет виджетов, что я должен вернуть?

404 / NotFound - виджеты не найдены.

204 / NoContent - виджеты не найдены, поэтому нет содержимого для возврата

200 / Ok с пустым массивом - Ошибки не возникли, но мы обнаружили пустой массив, поэтому просто верните его.

Answer 1

Да, 404 будет правильным кодом возврата для несуществующей компании, потому что если вы должны вернуть код успеха, разработчик, использующий ваш API, должен будет добавить дополнительные проверки для этого, или вам придется прийти с поддельными данными для выполнения запроса. Кроме того, в большинстве языков есть простые способы проверки и обработки кодов ошибок.

Что касается виджетов, поскольку это массив, это действительно ваше дело. Хотя коды 4xx указывают на ошибку. Именно поэтому я лично рекомендовал бы использовать 204 или 200, так как 2xx указывает на успех. 404 будет более уместным, если они попытаются получить список виджетов для несуществующей компании.

В действительности это сводится к последовательности и простоте. Большинство API всегда будут просто использовать код 200 и возвращать пустой массив в этом случае, потому что тогда разработчик, использующий API, может (обычно) использовать тот же или аналогичный код для обработки запросов, независимо от того, пуст массив или нет. Если вы возвращаете другой код состояния (204), а не просто пустой массив, разработчик, использующий ваш API, должен будет добавить дополнительную проверку для этого и, скорее всего, все равно создаст и вернет пустой массив. Кроме того, он избавляется от лишней пары строк в размещенном вами коде.