ASP.NET Core: Створення першого веб-API з використанням ASP.NET Core MVC і Visual Studio

Протокол HTTP може використовуватися не тільки для веб-сторінок. Це ще й потужна платформа для створення API, що надають сервіси і дані. Протокол HTTP простий, гнучкий і широко поширений. Практично будь-яка існуюча платформа має бібліотеку HTTP, тому служби HTTP доступні в великому числі клієнтів, включаючи браузери, мобільні пристрої і традиційні офісні додатки.

У новій статті з серії ASP.NET Core буде описано створення простого веб-API для роботи зі списком справ.



ASP.NET Core MVC має вбудовану підтримку створення веб-API. Об'єднання двох платформ спрощує створення додатків, що включають як користувальницький інтерфейс (HTML), так і API, так як в цьому випадку у них буде спільний код і конвеєр.

Примітка: якщо ви портируете існуючий додаток веб-API ASP.NET Core, прочитайте про те, як перейти з веб-API ASP.NET.

Опис
У цій статті будемо створювати наступний API:
API Опис Тіло запиту Тіло відповіді
GET /api/todo Отримати всі елементи списку справ Немає Масив елементів списку справ
GET /api/todo/{id} Отримати елемент з ідентифікатором Немає Елемент списку справ
POST /api/todo Додати новий елемент Елемент списку справ Елемент списку справ
PUT /api/todo/{id} Оновити існуючий елемент Елемент списку справ Немає
PATCH /api/todo/{id} Оновити існуючий елемент Елемент списку справ Немає
DELETE /api/todo/{id} Видалити елемент Немає Немає
На діаграмі нижче показана архітектура програми:



  • Клієнтом є, який використовує веб-API (браузер, мобільний додаток і інше). У нашій статті клієнт не створюється. Для тестування програми буде використовуватися Postman.
  • Модель — це об'єкт, який представляє дані в нашому додатку. У цьому випадку єдина модель — це елемент списку справ. Моделі представлені простими класами C# (POCO).
  • Контролер — це об'єкт, який обробляє HTTP-запит і створює HTTP-відповідь. В даному додатку один контролер.
  • Для простоти в цьому матеріалі для роботи програми не буде використовуватися база даних. Замість цього елементи списку просто зберігаються в пам'яті. Однак рівень доступу до даних буде включений, щоб показати роздільність веб-API і рівня даних. Варіант з використанням бази даних описаний в статті.


Створення проекту
Запустіть Visual Studio. В меню File виберіть New > Project. Виберіть шаблон проекту ASP.NET Core Web Application (.NET Core). Назвіть проект
TodoApi
, зніміть позначку Host in the cloud і натисніть OK.



У вікні New ASP.NET Core Web Application (.NET Core) — TodoApi виберіть шаблон Web API. Натисніть OK.



Додавання класу моделі
Модель — це об'єкт, який представляє дані в нашому додатку. У цьому випадку єдина модель — це елемент списку справ.

Додайте каталог з ім'ям «Models». У браузері рішень натисніть праву кнопку миші на проекті. Виберіть пункт Add > New Folder. Ведіть ім'я каталогу Models.



Примітка: класи моделі можуть перебувати в будь-якому місці проекту, але зазвичай їх розміщують у каталозі Models.

Додайте клас
TodoItem
. Натисніть праву кнопку миші на теці Models і виберіть пункт Add > Class. Ведіть ім'я класу
TodoItem
та натисніть Add.

Замініть сформований код наступним:

namespace TodoApi.Models
{
public class TodoItem
{
public string Key { get; set; }
public string Name { get; set; }
public bool IsComplete { get; set; }
}
}

Додавання класу репозиторію
Репозиторій — це об'єкт, який інкапсулює рівень даних і містить логіку для отримання даних та напрями їх до моделі. Хоча в даному додатку не використовується база даних, має сенс показати, як можна впроваджувати в репозиторії контролери. Створіть код репозиторію в каталозі Models.

Почніть з визначення інтерфейсу репозиторію з назвою
ITodoRepository
. Використовуйте шаблон класу (Add New Item > Class).

using System.Collections.Generic;

namespace TodoApi.Models
{
public interface ITodoRepository
{
void Add(TodoItem item);
IEnumerable<TodoItem> GetAll();
TodoItem Find(string key);
TodoItem Remove(string key);
void Update(TodoItem item);
}
}

Цей інтерфейс визначає основні операції CRUD.

Потім додайте клас
TodoRepository
, який реалізує
ITodoRepository
:

using System;
using System.Collections.Generic;
using System.Collections.Concurrent;

namespace TodoApi.Models
{
public class TodoRepository : ITodoRepository
{
private static ConcurrentDictionary<string, TodoItem> _todos =
new ConcurrentDictionary<string, TodoItem>();

public TodoRepository()
{
Add(new TodoItem { Name = "Item1" });
}

public IEnumerable<TodoItem> GetAll()
{
return _todos.Values;
}

public void Add(TodoItem item)
{
item.Key = Guid.NewGuid().ToString();
_todos[item.Key] = item;
}

public TodoItem Find(string key)
{
TodoItem item;
_todos.TryGetValue(key, out item);
return item;
}

public TodoItem Remove(string key)
{
TodoItem item;
_todos.TryRemove(key, out item);
return item;
}

public void Update(TodoItem item)
{
_todos[item.Key] = item;
}
}
}

Побудуйте додаток, щоб переконатися, що компілятор не видає помилок.

Реєстрація репозиторію
При визначенні інтерфейсу репозиторію ми можемо відокремити клас сховища від контролера MVC, який його використовує. Замість реалізації
TodoRepository
всередині контролера ми впровадимо
TodoRepository
, використовуючи вбудовану в ASP.NET Core підтримку впровадження залежностей.

Такий підхід спрощує модульне тестування контролерів. Модульні тести впроваджують «фіктивну» або «імітаційну» версію
ITodoRepository
. В цьому випадку тест націлений на логіку контролера, а не на рівень доступу до даних.

Для впровадження репозиторію в контролер необхідно зареєструвати його за допомогою контейнерів DI. Відкрийте файл Startup.cs. Додайте наступну директиву using:

using TodoApi.Models;

В метод
ConfigureServices
додайте виділений код:

public void ConfigureServices(IServiceCollection services)
{
// Add services framework.
services.AddMvc();

services.AddSingleton<ITodoRepository, TodoRepository>();
}

Додавання контролера
У браузері рішень натисніть праву кнопку миші на теці Controllers. Виберіть пункт Add > New Item. У вікні Add New Item виберіть шаблон Web API Controller Class. Введіть ім'я класу
TodoController
.

Замініть сформований код наступним:

using System.Collections.Generic;
using Microsoft.AspNetCore.Mvc;
using TodoApi.Models;

namespace TodoApi.Controllers
{
[Route("api/[controller]")]
public class TodoController : Controller
{
public TodoController(ITodoRepository todoItems)
{
TodoItems = todoItems;
}
public ITodoRepository TodoItems { get; set; }
}
}


Таким чином визначається клас порожнього контролера. У наступних розділах описується додавання методів для реалізації API.

Отримання елементів списку справ
Щоб отримати елементи списку справ, додайте наступні методи в клас
TodoController
:

public IEnumerable<TodoItem> GetAll()
{
return TodoItems.GetAll();
}

[HttpGet("{id}", Name = "GetTodo")]
public IActionResult GetById(string id)
{
var item = TodoItems.Find(id);
if (item == null)
{
return NotFound();
}
return new ObjectResult(item);
}

Ці методи реалізують два методу GET:

  • GET /api/todo
  • GET /api/todo/{id}
В даному випадку HTTP-відповідь для методу
GetAll
буде наступним:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Server: Microsoft IIS/10.0
Date: Thu, 18 Jun 2015 20:51:10 GMT
Content-Length: 82

[{"Key":"4f67d7c5-a2a9-4aae-b030-16003dd829ae","Name":"Item1","IsComplete":false}]

Далі розповімо, як можна переглядати HTTP-відповіді за допомогою Postman.

Маршрутизація та URL-шляху

Атрибут
HttpGet
(HttpGetAttribute) визначає метод HTTP GET. URL-шлях для кожного методу будується наступним чином:

  • Візьміть рядок шаблону з атрибута route контролера:
    [Route("api/[controller]")]
  • Замініть [Controller] на ім'я контролера, яке ви отримаєте, взявши ім'я класу контролера і прибравши суфікс «Controller». У нашому прикладі ім'я класу контролера — TodoController, а кореневе ім'я — todo. Маршрутизація ASP.NET Core не враховує регістр символів.
  • Якщо атрибут
    [HttpGet]
    має рядок шаблону, додайте її до шляху. В даному прикладі рядок шаблону не використовується.
У методі
GetById
:

[HttpGet("{id}", Name = "GetTodo")]
public IActionResult GetById(string id)

"{id}"
— це величина, замінна на ідентифікатор елемента
todo
. Коли
GetById
викликається, значення "{id}" в URL присвоюється параметру
id
методу.

Name = "GetTodo"
створює іменований маршрут, що дозволяє посилатися на нього в HTTP-відповіді. Надалі це буде показано на прикладі.

Повертає значення

Метод
GetAll
повертає
IEnumerable
. MVC автоматично серіалізует об'єкт в JSON і записує JSON в тіло відповіді. Код відповіді для цього методу — 200, в тому випадку якщо немає необроблених винятків (необроблені виключення переводяться в помилки 5xx.)

У свою чергу метод
GetById
повертає значення більш загального типу
IActionResult
, який представлений великою кількістю типів значень.
GetById
має два різних типи значень:

  • Якщо немає відповідності запитуваній ідентифікатором, метод повертає помилку 404. Це відбувається при поверненні
    NotFound
    .
  • В інших випадках метод повертає код 200 і тіло відповіді у форматі JSON. Це відбувається при поверненні
    ObjectResult
    .

Запуск програми

Натисніть сполучення клавіш CTRL+F5 в Visual Studio, щоб запустити програму. Відкриється браузер і відкриється веб-сторінка
http://localhost:port/api/values
, де port є довільно обраним номером порту. Якщо використовується Chrome, Edge або Firefox, будуть відображені дані. При використанні IE буде запропоновано відкрити або зберегти файл values.json.

Реалізація інших операцій CRUD
Додамо методи
Create
,
Update
та
Delete
. Цей процес аналогічний тому, про що мова йшла раніше, тому тут буде показаний код та виділено основні відмінності. Створіть проект після додавання або зміни коду.

Create

[HttpPost]
public IActionResult Create([FromBody] TodoItem item)
{
if (item == null)
{
return BadRequest();
}
TodoItems.Add(item);
return CreatedAtRoute("GetTodo", new { id = item.Key }, item);
}

Це метод HTTO POST, вказаний в атрибуті [HttpPost]. Атрибут [FromBody] посилає команду MVC отримати значення елемента списку справ з тіла HTTP-запиту.

Метод CreatedAtRoute повертає відповідь 201, який є стандартною відповіддю для HTTP методу POST, створює новий ресурс на сервері.
CreateAtRoute
також додає у відповідь заголовок Location. Заголовок Location вказує URL створеного елемента списку справ. Опис: 10.2.2 201 Created.

Використання Postman для відправки запиту Create



  • Виберіть
    POST
    HTTP методу.
  • Виберіть пункт Body.
  • Виберіть пункт raw.
  • Виберіть тип JSON.
  • У редакторі пар ключ-значення вкажіть елемент Todo наступним чином:
    {"Name":"<your to-do item>"}
    .
  • Натисніть Send.
Виберіть закладку Headers та скопіюйте заголовок Location:



Для доступу до ресурсу, який тільки що створений, можна використовувати URL заголовку Location. Повторно викличте метод
GetById
, який створив іменований маршрут
"GetTodo"
:

[HttpGet("{id}", Name = "GetTodo")]
public IActionResult GetById(string id)

Update

[HttpPut("{id}")]
public IActionResult Update(string id, [FromBody] TodoItem item)
{
if (item == null || item.Key != id)
{
return BadRequest();
}

var todo = TodoItems.Find(id);
if (todo == null)
{
return NotFound();
}

TodoItems.Update(item);
return new NoContentResult();
}

Update
подібний
Create
, але використовує HTTP PUT. Відповідь 204 (Немає вмісту). Згідно специфікації по HTTP по запиту PUT потрібно, щоб клієнт відправив оновлений об'єкт повністю, а не тільки дельти. Для підтримки часткових оновлень використовуйте HTTP PATCH.



Update з використанням Patch

Аналогічно
Update
, але з використанням HTTP PATCH. Відповідь 204 (Немає вмісту).

[HttpPatch("{id}")]
public IActionResult Update([FromBody] TodoItem item, string id)
{
if (item == null)
{
return BadRequest();
}

var todo = TodoItems.Find(id);
if (todo == null)
{
return NotFound();
}

item.Key = todo.Key;

TodoItems.Update(item);
return new NoContentResult();
}



Delete

[HttpDelete("{id}")]
public IActionResult Delete(string id)
{
var todo = TodoItems.Find(id);
if (todo == null)
{
return NotFound();
}

TodoItems.Remove(id);
return new NoContentResult();
}

Відповідь 204 (Немає вмісту).



Серія статей ASP.NET Core:

1. ASP.NET Core на Nano Server.
2. ASP.NET Core: Створення зовнішнього інтерфейсу веб-служби для програми.
3. ASP.NET Core: Створення першого веб-API з використанням ASP.NET Core MVC і Visual Studio.
4. ASP.NET Core: Розгортання веб-додатків в службі додатків на Microsoft Visual Studio.
5. ASP.NET Core: Ваше перше додаток на Mac з використанням Visual Studio Code.
Джерело: Хабрахабр

0 коментарів

Тільки зареєстровані та авторизовані користувачі можуть залишати коментарі.