Настройка запросов в ASP.NET API: атрибуты HttpGet/HttpPost, маршруты, query-параметры и свои методы контроллера

В прошлой лекции мы с вами сгенерировали рабочее API. Он генерирует 5 дефолтных запросов для каждой таблицы. Но если у нас появляется нужда в создании своих запросов или изменении существующих, нам нужно понять как работают контроллеры.

Структура контроллера #

Возьмем API с прошлой пары и откроем контроллер человека — HumenController. Начнем сверху.

1
namespace MyTestApi.Controllers
2
{
3
    [Route("api/[controller]")]
4
    [ApiController]
5
    public class HumenController : ControllerBase
6
    {
7
        private readonly ExampleDBContext _context;
8

9
        public HumenController(ExampleDBContext context)
10
        {
11
            _context = context;
12
        }
13
        // ...
14
    }
15
}

Первое что мы видим — штуки в квадратных скобках. Они называются атрибуты. Подобные вещи мы видели, когда писали тесты. Напомню, атрибуты — надстройки над кодом, которые определяют её поведение. Так:

• Route — говорит по какому URL будет доступно это API.
• ApiController — говорит, что это не просто класс, а класс для API.

Потом мы видим переменную _context. В ней хранится вся БД и через неё мы можем обращаться ко всем табличкам как коллекциям (List<Human>, List<Colour> и прочее). А чтобы переменная не была пустой, ей автоматически дается значение в public HumenController.

Атрибут HttpGet и возврат данных #

Каждый запрос — отдельный метод с нужным атрибутом. Например GET запрос.

1
// GET: api/Humen
2
[HttpGet]
3
public async Task<ActionResult<IEnumerable<Human>>> GetHumans()
4
{
5
    if (_context.Humans == null)
6
    {
7
        return NotFound();
8
    }
9
    return await _context.Humans.ToListAsync();
10
}

Он помечен атрибутом HttpGet и возвращает коллекцию с Human, которая потом автоматом преобразуется в JSON. Название метода тут не играет роли.

Внутри из переменной _context метод спокойно берёт таблицу Humans и возвращает все данные из неё. Вернуть метод может не только данные, но и какой-нибудь статус-код, как например, 404 — NotFound.

(Таких методов кстати очень много — Ok, BadRequest, NoContent и прочее. Какой они возвращают статус-код вы можете узнать, наведясь на сам метод.)

GET по ID и параметры в маршруте #

Чуть ниже есть GET запрос по Id. В комментарии показано как к нему нужно обращаться — api/Humen/5.

1
// GET: api/Humen/5
2
[HttpGet("{id}")]
3
public async Task<ActionResult<Human>> GetHuman(int id)
4
{
5
    if (_context.Humans == null)
6
    {
7
        return NotFound();
8
    }
9

10
    var human = await _context.Humans.FindAsync(id);
11

12
    if (human == null)
13
    {
14
        return NotFound();
15
    }
16

17
    return human;
18
}

Здесь мы уже видим отличия. Кроме как кода, который ищет запись по id и, если он её нашел, возвращает её (а если не нашел — статус-код 404), мы ещё видим, что в атрибуте HttpGet появились круглые скобки с "{id}" внутри, и появилась переменная int id в методе. Как они связаны?

Когда в запросе (не важно, HttpGet, HttpPost, HttpPut и прочее) появляются круглые скобки с текстом внутри, они перезаписывают обращение к этому методу. В этом случае мы уже видим, что к дефолтному api/Humen добавляется число.

Если я хочу поменять обращение, я сделаю вот так:

1
[HttpGet("getbyid/{id}")]
2
public async Task<ActionResult<Human>> GetHuman(int id)

Запрос будет выглядеть вот так:

Я поставлю слеш перед getbyid:

1
[HttpGet("/getbyid/{id}")]

И то, что было до этого (api/Humen) полностью уберется.

Также заметим, что в этих фигурных скобках написано название нашей переменной. Соответственно, если я её поменяю, то и в запросе её также нужно поменять.

Обращение всё равно каким было, так и останется — https://localhost:порт/getbyid/5.

Query-параметры #

А вот если я вовсе уберу этот {переменная} из моего пути, тогда обращение поменяется.

1
[HttpGet("/getbyid/")]
2
public async Task<ActionResult<Human>> GetHuman(int superHumanId)

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

В таком виде данные обычно отправляются если они не обязательны, а являются просто как надстройка. Возьмем например ютуб:

• https://youtu.be/dQw4w9WgXcQ — это обычная ссылка на видео.
• https://youtu.be/dQw4w9WgXcQ?t=43 — это ссылка с таймкодом — необязательная вещь, открывает всю ту же страницу, но если данные были переданы, тогда происходит что-то дополнительно.

В случае, если ссылка та же, но мы хотим вывести вообще другое, лучше использовать ссылка/данные. Если ввод этих данных опционален, мы делаем ссылка?переменная=данные. Ещё полезно, когда переменных много.

SaveChangesAsync для изменений #

Со всеми остальными запросами происходят такие же действия, только в добавлении/изменении/удалении данных есть одна интересная строчка — сохранение изменений. Вот например в удалении.

Эта строчка должна быть в конце каждого запроса, если мы как-либо изменяем данные. Так они сохранятся в БД.

Свой запрос в контроллере #

На основе этих знаний мы можем создать свои методы в контроллере — свои запросы. Вот скажем я хочу сделать запрос, который возьмет всех людей, которые любят какой-то цвет, который я им передам. Если я хочу получить данные, ничего зашифрованного отправлять не собираюсь, это будет Get запрос. Создам такой метод где-то ниже. Метод будет мне возвращать коллекцию с людьми, так как людей, которые любят, например, зеленый цвет, может быть много.

1
[HttpGet]
2
public async Task<ActionResult<List<Human>>> GetHumansByColour()
3
{
4

5
}

Добавлю интовую переменную, в которую я буду передавать айдишник цвета.

1
GetHumansByColour(int colourId)

В HttpGet напишу путь до этого запроса.

1
[HttpGet("GetByColourId/{colourId}")]
2
public async Task<ActionResult<List<Human>>> GetHumansByColour(int colourId)
3
{
4

5
}

И напишу код.

1
public async Task<ActionResult<List<Human>>> GetHumansByColour(int colourId)
2
{
3
    if (_context.Humans == null)          // если записей в таблице нет вовсе
4
    {
5
        return NotFound();                // вернуть 404
6
    }
7

8
    var humans = _context.Humans.ToList().Where(x =>    // ищу все записи в таблице,
9
                x.ColourId == colourId);                // где ColourId равен тому, что я передала
10

11
    if (humans == null || humans?.Count() == 0)         // если и тут ничего нет
12
    {
13
        return NotFound();                              // вернуть 404
14
    }
15
    return Ok(humans);                                  // возвращаю лист с статусом 200 — всё ок
16
}

Запущу API чтобы посмотреть, как будет работать мой метод. Во-первых я сразу вижу, что мой метод появился в Swagger.

Выполняя запрос, он мне возвращает всех людей, которые любят этот цвет. В нашем случае это только одна девушка — Василиса, но даже в этом случае API вернуло коллекцию (потому что в JSON есть квадратные скобки).

Полный код примера #

Controllers/HumenController.cs — стандартные запросы плюс свой GetByColourId:

1
using Microsoft.AspNetCore.Mvc;
2
using Microsoft.EntityFrameworkCore;
3
using MyTestApi.Models;
4

5
namespace MyTestApi.Controllers
6
{
7
    [Route("api/[controller]")]
8
    [ApiController]
9
    public class HumenController : ControllerBase
10
    {
11
        private readonly ExampleDBContext _context;
12

13
        public HumenController(ExampleDBContext context)
14
        {
15
            _context = context;
16
        }
17

18
        // GET: api/Humen
19
        [HttpGet]
20
        public async Task<ActionResult<IEnumerable<Human>>> GetHumans()
21
        {
22
            if (_context.Humans == null)
23
                return NotFound();
24
            return await _context.Humans.ToListAsync();
25
        }
26

27
        // GET: api/Humen/5
28
        [HttpGet("{id}")]
29
        public async Task<ActionResult<Human>> GetHuman(int id)
30
        {
31
            if (_context.Humans == null)
32
                return NotFound();
33

34
            var human = await _context.Humans.FindAsync(id);
35
            if (human == null)
36
                return NotFound();
37

38
            return human;
39
        }
40

41
        // DELETE: api/Humen/5
42
        [HttpDelete("{id}")]
43
        public async Task<IActionResult> DeleteHuman(int id)
44
        {
45
            var human = await _context.Humans.FindAsync(id);
46
            if (human == null)
47
                return NotFound();
48

49
            _context.Humans.Remove(human);
50
            await _context.SaveChangesAsync();
51
            return NoContent();
52
        }
53

54
        // Свой запрос: GET api/Humen/GetByColourId/2
55
        [HttpGet("GetByColourId/{colourId}")]
56
        public async Task<ActionResult<List<Human>>> GetHumansByColour(int colourId)
57
        {
58
            if (_context.Humans == null)
59
                return NotFound();
60

61
            var humans = _context.Humans.ToList().Where(x => x.ColourId == colourId);
62

63
            if (humans == null || humans?.Count() == 0)
64
                return NotFound();
65

66
            return Ok(humans);
67
        }
68
    }
69
}