В процессе изучения ASP.NET Core и, в целом языка программирования C#, мы довольно часто используем аббревиатуру API, особо не вдаваясь в подробности того, что эта аббревиатура представляет и что означает. В этой части мы разберемся с тем, что из себя представляет API и посмотрим, в общих чертах, на возможности создания Web API в ASP.NET Core.
Что такое API?
API (Application Program Interface) — программный интерфейс, обеспечивающий взаимодействие одного приложения с другим (или одной части приложения с другой частью приложения). В общих чертах. под API можно понимать набор способов взаимодействия чего-то с чем-то. Например, когда мы пишем свое приложение для формирования отчётов в формате MS Word, мы создаем графический интерфейс приложения, определяем какие-то методы, с помощью которых формируется набор данных для будущего отчета и, когда пользователь нажимает кнопку «Создать отчёт», наше приложение взаимодействует с API, который нам предоставляет офисный пакет Microsoft. При этом, для пользователя, всё это выглядит как «чёрный ящик»: нажал кнопку — получил отчёт. При этом, наше приложение может вызывать десятки методов API, чтобы сформировать документ. Таким образом, мы используем уже готовые методы API, не вникая глубоко в особенности формата документа Word и способы его формирования — мы формируем документ посредствам взаимодействия с API.
Аналогичным образом мы, как пользователи, регулярно используем различные Web API, т.е. программные интерфейсы, используемые для взаимодействия в Сети. Например, когда мы покупаем билеты в кино, смотрим прогноз погоды на Яндексе или ищем что-то в Сети. Для нас (пользователей) все эти действия выглядят просто и понятно — мы используем графический интерфейс приложения (GUI). При этом, внутри самого приложения могут происходить десятки вызовов методов различных Web API для получения результата. При этом, то, что вызывается в том или ином API, например, какие-то методы — строго определено и заранее известно разработчику приложения.
Таким образом, API, образно, можно представить как контракт между двумя сторонами — между вызывающей стороной (клиентом) и сервером. Клиент обязуется осуществлять те или иные вызовы, используя требования, предъявляемые сервером (например, требование использовать определенные заголовки в запросах), а сервер обязуется вернуть ответ клиенту, содержащий необходимые данные, или сведения об ошибке, если клиент не придерживается заданных требований или сервер по каким-либо причинам не в состоянии сформировать ответ.
Зачем разрабатывать API?
Любой API отвечает на три главных вопроса:
- Как можно обращаться к API? Для ответа на этот вопрос у API обычно имеются набор функций или конечных точек к которым может обращаться клиент API
- Какие данные используются на входе? Ответ на этот вопрос, обычно, содержит какие-либо классы, объекты, константы мы должны отправлять на сервер и, при этом, описание этих данных должно быть доступно клиенту, например, по средствам документации.
- Какие данные поступят на выходе?
Опять же, немного упрощая, можно сказать, что API — это некое приложение без графического интерфейса. Всё, что делает API — это взаимодействует с данными. API можно создать, чтобы дать доступ сторонним разработчикам к каким-то функциям своего приложения. Например, в последние несколько лет, большинство из нас активно использует так называемые, «облачные» хранилища данных — Google.Drive, Яндекс.Диск, Dropbox и т.д. для хранения каких-то файлов. Практически любое такое «облако» помимо уже готовых приложений для пользователей, предоставляет также и свой API для разработчиков. Тот же Яндекс.Диск, например, дает возможность использовать своё «облако» для хранения данных нашего приложения.
Второй момент, когда нам можно создать свой API — при разработке большого приложения для того, чтобы отделить бизнес-логику от графического интерфейса. По сути, когда мы разбирались с ASP.NET Core MVC, мы разрабатывали свой API, используя для этого контроллеры и модели данных. И, уже после того, как был создан контроллер, мы использовали его методы в графическом интерфейсе (представлениях).
Третий момент, когда можно разработать свой API — это случай, когда нам просто незачем использовать графический интерфейс приложения. Например, разрабатывается большая система расчёта каких-то сложных объектов и предполагается, что вся бизнес-логика будет написана на C#, а графический интерфейс — на JavaScript или, вообще, на чём-то экзотическом. В этом случае, разработчик C#, по сути, создает API, который будет оперировать данными — считывать данные из БД, производить сложные расчёты и выдавать результат в виде каких-то относительно простых объектов, например, в формате JSON. Клиентом, в этом случае, будет выступать приложение с графическим интерфейсом, которое будет полученные данные каким-либо образом визуализировать.
API в ASP.NET Core
ASP.NET Core поддерживает два подхода к созданию API
- подход на основе контроллера
- минимальные API.
Что касается минимального API, то с ним мы работали, когда разбирались с базовыми возможностями ASP.NET Core. Такой подход к разработке можно применять, например, на этапе создания прототипа своего приложения или для проверки каких-либо возможностей/частей приложения. При таком подходе, по умолчанию, отсутствуют некоторые возможности ASP.NET Core, полезные при разработке приложений. Например, отсутствует встроенная поддержка привязки модели или её валидации. Конечно, эти и другие, отсутствующие возможности можно добавить в проект минимального API, но зачем, если есть второй подход построения API — на основе контроллеров.
При использовании подхода построения API на основе контроллеров мы создаем один или несколько контроллеров — классов, содержащих необходимые методы API. Построение API на основе контроллеров — это наиболее предпочтительный и используемый в настоящее время, способ построения Web API. Именно с этим подходом мы и будем знакомиться далее. Для того, чтобы более полно представлять себе работу с контроллерами, рекомендую Вам предварительно ознакомиться с возможностями ASP.NET Core MVC, а именно — с частью о контроллерах.
Итого
Программный интерфейс (API) — это набор правил взаимодействия между приложениями или частями одного приложения между собой. ASP.NET Core предоставляет два подхода к построению API — минимальные API и API на основе контроллеров. В дальнейшем, мы будем использовать второй подход к построению API.