Независимо от того, являетесь ли вы новым разработчиком или просто заинтересованы в том, чтобы начать заниматься веб-разработкой, важно иметь четкое представление об RESTful API (приложениях и программных интерфейсах).

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

Для этого руководства вам понадобится Visual Studio (предпочтительно 2022) и Postman, который представляет собой инструмент для проектирования, тестирования и документирования API с функциями совместной работы. Если вы не знакомы с Postman, вам необходимо установить его и пройти краткое руководство по основам.

Что такое API?

Интерфейс прикладного программирования (API) — это программный посредник, который обеспечивает связь между различными приложениями в автоматическом режиме без необходимости прямого взаимодействия с пользователем. Это позволяет одной системе запрашивать и получать данные от другой, предоставляя программным системам возможность автоматизировать процессы и интегрироваться путем обмена информацией и функциями. Доступны многие популярные API, например, API социальных сетей. например, Facebook и Twitter, платежные API, такие как PayPal, и погодные API, такие как OpenWeatherMap и AccuWeather.

Что такое RESTful API?

RESTful API — это тип API, в котором используется передача репрезентативного состояния (REST), широко используемый стиль архитектуры программного обеспечения для создания веб-служб. Архитектура REST следует модели клиент-сервер, которая отделяет клиент от сервера, позволяя им работать независимо. RESTful API обеспечивает связь между ними с помощью протокола HTTP. Протокол HTTP предоставляет стандартные методы для выполнения таких действий, как GET, POST, PUT и DELETE. Эти методы используются для получения и отправки данных с/на сервер для обработки, обновления существующих ресурсов и удаления ресурсов с сервера соответственно.

HTTP-методы, используемые RESTful API:

  1. GET: метод GET используется для получения информации с сервера.
  2. POST: метод POST используется для отправки данных на сервер для обработки.
  3. PUT: метод PUT используется для обновления существующих ресурсов на сервере.
  4. DELETE: метод DELETE используется для удаления ресурсов с сервера.

Коды состояния HTTP

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

Коды состояния HTTP имеют формат YXX, где Y указывает тип ответа. Например:

  • 1XX, ответ указывает на информационные запросы,
  • 2XX, ответ указывает на успешные запросы,
  • 3XX, ответ указывает на перенаправление,
  • 4XX, ответ указывает на ошибку клиента,
  • 5XX ответ указывает на ошибки сервера.

Некоторые из наиболее популярных кодов состояния HTTP, возвращаемых RESTful API, включают:

  • 200 ОК (успешно),
  • 201 CREATED (ресурс создан),
  • 204 NO CONTENT (запрос выполнен успешно, нет контента для возврата),
  • и т. д.

Создание API в .NET

Создание API — это эффективный способ создания масштабируемых, производительных и безопасных веб-сервисов. В контексте .NET разработчики могут выбирать между использованием .NET Framework или .NET Core. статья. Платформа ASP.NET Core предоставляет разработчикам ряд современных инструментов и методов. Он также предлагает набор ключевых функций, включая мощную систему маршрутизации, компоненты промежуточного программного обеспечения для обработки аутентификации и авторизации, а также поддержку нескольких форматов ввода и вывода. В этой статье мы рассмотрим преимущества создания API в .NET с использованием платформы ASP.NET Core, а также то, как разработчик можно начинать без опыта.

Создание проекта

На данный момент мы собираемся сделать наш первый проект веб-API. Во-первых, нам нужно открыть нашу Visual Studio, создать новый проект, выбрать ASP.NET Core Web API и назвать наш API как FirstAPI, затем нажмите Далее.

Мы собираемся использовать .NET 6.0 без поддержки HTTPS или Swagger, как показано ниже.

Давайте теперь очистим наше решение, удалив следующие два файла (WeatherForecastController.cs, WeatherForecastController.cs), чтобы сделать наш проект простым, а затем нам нужно перейти к нашему launchSettings.json и закомментируйте launchBrowser и launchUrl в профилях. Наконец, нам нужно убедиться, что applicationUrl легко доступен, поэтому я предлагаю сделать это примечанием.

Теперь мы готовы начать.

Что такое контроллер веб-API в C#?

Важным компонентом в реализации RESTful API является контроллер. Он создается путем определения класса, производного от класса System.Web.Http.ApiController, который отвечает за обработку запросов HTTP и управление ответами HTTP. Контроллер определяет конечные точки (URL) для веб-API и методы, которые выполняются при выполнении запроса к каждой конечной точке. Он реализует все методы действий, которые определяют методы HTTP (GET, POST, PUT, DELETE) и параметры требуется для обработки запроса.

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

Создаем наш первый контроллер

Щелкните правой кнопкой мыши папку Контроллеры и выберите Добавить, затем Контроллер… и выберите Контроллер MVC — Пустой.

Затем выберите APIController — Empty и назовите его TestController. Важно, чтобы все файлы, существующие в папке Controllers, заканчивались как Controller.cs, так как это соглашение об именах.

Поздравляем, вы только что сделали свой первый контроллер! Теперь ваше решение должно выглядеть так, как показано на изображении ниже.

Давайте теперь объясним, что представляет собой каждый из них:

Папка "Контроллеры"

Каталог, в который мы должны поместить наши контроллеры.

Атрибут маршрута

Атрибут Route в C# ASP.NET Core используется для определения маршрута URL для конкретного метода действия контроллера. Этот атрибут сопоставляет входящие HTTP-запросы с определенными методами действий контроллера. По умолчанию значением атрибута Route является «api/[controller]». Это означает, что для доступа к методам этого контроллера необходимо нажать URL: « applicationUrl/» + «api/» + «имя контроллера без слова Controller в конце». Например, если контроллер называется «TestController», URL-адрес с учетом того, что мой applicationUrl имеет вид «https://localhost:5164», будет быть «https://localhost:5164/api/Test». Однако многие разработчики предпочитают изменять часть [controller] на что-то статичное, чтобы избежать проблем, если файл будет переименован в будущем.

Атрибут ApiController

В C# ASP.NET Core атрибут ApiController используется для идентификации класса как контроллера API. Этот атрибут применяет к контроллеру определенное поведение, которое предназначено для создания API, а не традиционных контроллеров MVC, используемых для создания веб-приложений. Применение этого атрибута включает несколько вариантов поведения по умолчанию, например автоматические ответы HTTP 400 при возникновении ошибок привязки или проверки модели. Важно всегда включать этот атрибут для контроллеров API, если только вы не понимаете, почему он может вам не понадобиться.

База управления

В C# ASP.NET Core ControllerBase — это базовый класс для контроллеров, который предоставляет набор функций для обработки HTTP-запросов и ответов. Когда вы наследуете класс контроллера от ControllerBase, вы получаете доступ к нескольким функциям, таким как доступ к HttpContext. Важно всегда наследовать от этого базового класса, если у вас нет четкого понимания, почему он может вам не понадобиться.

Давайте теперь создадим фиктивный класс пользователя и класс для имитации базы данных, а затем перейдем к нашему первому методу.

Мы поместим наш класс User в новый каталог с именем Models.

Мы максимально упростили этот класс, включив в него только два поля: целочисленный идентификатор и строковое имя. Обычно мы храним этот объект в нашей базе данных и предоставляем доступ к другому объекту с именем Data Transfer Object (DTO). Преобразование одного типа объекта в другой можно выполнить вручную или с помощью преобразователя, такого как AutoMapper. Однако в контексте этого руководства мы не будем выполнять это преобразование.

Давайте теперь создадим объект, который будет имитировать нашу базу данных. Мы сделаем этот объект статическим и поместим его в новый каталог с именем Data.

Соглашение об именовании

Соглашение об именах для методов внутри контроллера обычно следует шаблону «Глагол» + «Существительное», чтобы описать действие, которое метод выполняет с ресурсом. Глагольная часть имени соответствует HTTP-глаголу, используемому для взаимодействия с ресурсом (например, GET, POST, PUT, DELETE). ), а именная часть соответствует названию ресурса.

Например, если у вас есть контроллер для управления пользователями, некоторые распространенные имена методов могут включать:

· GetAllUsers() (команда GET для получения всех пользователей)

· GetUser(int id) (GET команда для получения определенного пользователя по идентификатору)

· CreateUser(Пользователь-пользователь) (POSTглагол для создания нового пользователя)

· UpdateUser(int id, User user) (PUT глагол для обновления существующего пользователя по идентификатору)

· DeleteUser(int id) (DELETEглагол для удаления пользователя по идентификатору)

Также принято включать глагол HTTP в качестве атрибута самого метода, используя такие атрибуты, как [HttpGet], [HttpPost], [HttpPut] и [HttpDelete]. Это делает более явным, какой HTTP-глагол соответствует каждому методу, а также помогает предотвратить конфликты имен, когда несколько методов имеют одно и то же имя, но разные атрибуты.

Теперь мы начнем с создания нашего первого метода GetUsers.

Метод GetUsers

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

Чтобы проверить этот метод, мы будем использовать инструмент Почтальон.

Чтобы выполнить запрос к нашему приложению, мы будем использовать applicationUrlиз launchSettings.json, а также URL-адрес маршрута нашего контроллера, как показано на рисунке ( 2). Важно отметить, что мы будем делать запрос HTTP GET (как указано в (1)). Результаты этого запроса показаны ниже в (3).

Поздравляем, вы сделали свой первый метод!

Метод GetUser

Давайте теперь создадим новый метод, который будет извлекать конкретный объект User по его идентификатору, если он существует. Если нет, он возвращает ноль.

Как видите, для этого метода требуется параметр Id, который будет передан контроллеру как часть URL-адреса, как показано ниже. Поскольку у нас есть два метода HTTPGET, мы можем помочь нашему контроллеру, указав, что новый метод требует передачи параметра. Это достигается путем добавления необходимой информации о параметрах в атрибут HttpGet.

Метод CreateUser

Теперь давайте попробуем создать новый метод, который будет создавать нового Пользователя с заданным именем. Мы назовем этот метод «CreateUser», и он будет принимать одну строковую переменную, которая будет именем пользователя. Он создаст новый пользовательский объект с заданным именем и следующим доступным идентификатором и, наконец, вернет нового пользователя. Метод должен выглядеть так, как показано ниже.

Теперь приступим к тестированию. Сложность здесь заключается в том, как передать значение имени в наш контроллер. Для этого нам нужно передать переменную в наш запрос. Обратите внимание, что этот метод использует метод HTTP POST. Давайте создадим нового Пользователя по имени Джон.

1. Обязательно сделайте POSTзапрос сейчас.
2. Передайте имя в качестве параметра запроса.
3. Посмотрите на результаты! Новый пользователь должен быть создан.

При желании теперь вы можете выполнить метод GetUsers, который мы сделали ранее, чтобы гарантировать создание нашего нового Пользователя.

Маршрутизация

Теперь поговорим о маршрутизации. Под маршрутизацией понимается процесс сопоставления входящих HTTP-запросов с определенными методами действий в веб-контроллере API с использованием определенной таблицы маршрутизации.

Шаблон таблицы маршрутизации по умолчанию — «api/{controller}/{id}».

Когда контроллер получает HTTP-запрос и пытается сопоставить URI с одним из шаблонов маршрутов в таблице маршрутизации, если маршрут не совпадает, клиент получает ошибку 404. Следующая стратегия используется веб-API для сопоставления входящих запросов с соответствующими методами действия:

· Web API добавляет «Контроллер» к значению переменной {controller}.

· Web API просматривает глагол HTTP, а затем ищет действие, имя которого начинается с имени этого глагола HTTP.

· Другие переменные-заполнители в шаблоне маршрута, такие как {id}, сопоставляются с параметрами действия.

Например, для созданного нами контроллера имеем:

Следующие шаги

Теперь вы знаете основы RESTful API и знаете, как создать свой первый простой проект. Если вы заинтересованы в расширении своих знаний, вы можете приступить к следующим задачам (или некоторым из них):

1. Разработайте действие DELETE, которое должно получать идентификатор в качестве параметра и удалять соответствующего Пользователя.

2. Создайте новый объект UserDTO и верните его своим потребителям вместо объекта User. Новый UserDTO должен содержать только поле Name.

3. Узнайте о ActionResults и обновите нашу реализацию, чтобы она возвращала этот тип объекта.

4. Сделайте наши методы асинхронными.

5. Переименуйте файл с TestController на UsersController и убедитесь, что все работает как прежде. 😊

Вы можете найти код, который мы сделали здесь.

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

Если вам понравился этот пост, хлопайте в ладоши 👏

Рекомендации

  1. Что такое REST, RestFulApi
  2. Создание веб-API с помощью ASP.NET Core, Microsoft
  3. Маршрутизация в ASP.NET Web API, Microsoft