Letysite.ru

IT Новости с интернет пространства
0 просмотров
Рейтинг статьи
1 звезда2 звезды3 звезды4 звезды5 звезд
Загрузка...

Web api frist сбора данных

Использование Web API

Средство Web API основано на добавлении в приложение ASP.NET MVC Framework контроллера специального вида. Эта разновидность контроллеров, которая называется контроллером API , обладает двумя характеристиками:

Методы действий возвращают объекты моделей, а не объекты типа ActionResult.

Методы действий выбираются на основе HTTP-метода, используемого в запросе.

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

Отсутствие возможности у контроллера API генерировать HTML-разметку из представлений является причиной, по которой в одностраничных приложениях комбинируются стандартные приемы ASP.NET MVC Framework с Web API. Инфраструктура ASP.NET MVC Framework выполняет шаги, требуемые для доставки HTML-содержимого пользователю (включая аутентификацию, авторизацию, выбор и визуализацию представления). После того, как HTML-содержимое доставлено в браузер, запросы Ajax, генерируемые содержащимся внутри кодом JavaScript, будут обрабатываться контроллером Web API.

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

Создание контроллера Web API

Добавление средства Web API к приложению осуществляется исключительно просто. Частично это объясняется тем, что создается элементарная веб-служба, но также и интеграцией с лежащей в основе инфраструктурой ASP.NET MVC Framework. В папке Controllers проекта создается файл класса по имени WebController.cs, в котором определяется контроллер, как показано в примере ниже:

Это и все, что требуется для создания контроллера API. Контроллер API имеет пять методов действий, которые отображаются на функциональные возможности хранилища и предоставляют доступ через веб-службу к объектам Reservation.

Тестирование контроллера API

Вскоре будут даны пояснения, как работает контроллер API, но сначала необходимо выполнить простой тест. Запустите приложение. После того, как браузер загрузит корневой URL проекта, перейдите на URL вида /api/web. Результат, который будет получен, зависит от применяемого браузера. Если вы используете Internet Explorer, то получите предложение сохранить или открыть файл, содержащий данные JSON.

Если переход на упомянутый URL осуществлялся с помощью другого браузера, такого как Google Chrome, то браузер отобразит приведенные ниже XML-данные:

Здесь интересно отметить пару моментов. Первый заключается в том, что запрос URL вида /api/web производит список всех объектов модели вместе с их свойствами, из которого можно сделать вывод, что был вызван метод действия GetAllReservations() контроллера Reservation.

Второй момент касается того, что разные браузеры получают разные форматы данных. Если вы попробуете сделать это самостоятельно, то можете получить другие результаты, т.к. в более поздних версиях браузеров может измениться способ выдачи запросов, однако вы заметите, что одни результаты имеют формат JSON, а другие — формат XML. (Также должно стать понятно, почему в веб-службах формат JSON почти повсеместно заменил XML. Формат XML более многословен и труден в обработке, особенно в случае использования JavaScript.)

Разные форматы данных применяются из-за того, что Web API использует HTTP-заголовок Accept в запросе для определения, с каким типом данных клиент предпочитает работать. Браузер Internet Explorer получает данные JSON, поскольку отправляет следующий заголовок Accept:

Браузер указывает, что в первую очередь предпочитает содержимое text/html, а затем application/xhtml+xml. Последняя часть заголовка Accept выглядит как */* и означает, что браузер будет принимать любой тип данных, если первые два оказываются недоступными.

Средство Web API поддерживает форматы JSON и XML, но отдает предпочтение формату JSON, который и будет использоваться в ответ на часть */* заголовка Accept для Internet Explorer. А вот заголовок Accept, отправляемый браузером Google Chrome:

Важная часть заголовка выделена полужирным: браузер Google Chrome указывает, что предпочитает получать данные application/xml перед */*. Контроллер Web API учитывает это предпочтение и доставляет данные в формате XML. Об этом упоминается потому, что общей проблемой, связанной с Web API, является получение данных в нежелательном формате. Подобное происходит из-за того, что заголовок Accept выдает неожиданное предпочтение относительно формата или вообще отсутствует в запросе.

Работа контроллера API

Чтобы получить намного больше сведений о работе контроллера API, необходимо перейти на URL вида /api/web/3. Вы увидите следующие данные в формате XML (или в формате JSON, если применяется другой браузер):

На этот раз контроллер API возвратил детали объекта Reservation, значение свойства ReservationId которого соответствует последнему сегменту запрошенного URL. Формат и сегменты URL были описаны в статье Шаблоны URL, где объяснялась система маршрутизации ASP.NET MVC Framework.

Контроллеры API имеют собственную конфигурацию маршрутизации, полностью отделенную от остальных частей приложения. Для новых проектов Visual Studio создает стандартную конфигурацию в файле /App_Start/WebApiConfig.cs, содержимое которого приведено в примере ниже. Это один из файлов, которые Visual Studio добавляет в проект, если при его создании был отмечен флажок Web API.

Файл WebApiConfig.cs содержит маршруты, используемые контроллерами API, и применяет другие классы, отличающиеся от обычных маршрутов MVC, которые определены в файле RouteConfig.cs. Средство Web API реализовано как автономная функциональная возможность ASP.NET и может применяться за пределами инфраструктуры ASP.NET MVC Framework. Это означает, что в Microsoft продублировали ряд ключевых функций ASP.NET MVC Framework в пространстве имен System.Web.Http, чтобы обеспечить раздельное существование средств MVC и Web API. (При написании приложения ASP.NET MVC Framework такое дублирование выглядит странным, однако оно имеет смысл, т.к. в Microsoft пытаются ориентировать на использование средства Web API также и разработчиков, не применяющих шаблон MVC.)

Среда Visual Studio также помещает в метод Application_Start() класса Global.asax вызов Configure(), который добавит маршруты Web API к конфигурации приложения:

В результате приложение имеет два набора маршрутов: те, что используются для контроллеров ASP.NET MVC Framework, и те, что применяются для контроллеров Web API.

Выбор действия контроллером API

Стандартный маршрут Web API, который был показан в примере выше, имеет статический сегмент api, а также переменные сегментов controller и id, являющиеся необязательными. Ключевое отличие от обычного маршрута MVC состоит в том, что переменная сегмента action отсутствует — именно здесь формируется поведение контроллеров API.

Когда в приложение поступает запрос, соответствующий маршруту Web API, действие определяется на основе метода HTTP, используемого для выдачи запроса. При тестировании контроллера API путем запроса в браузере URL вида /api/reservation браузер укажет HTTP-метод GET.

Класс ApiController, который является базовым для контроллеров Web API, выясняет необходимый контроллер на основе маршрута и применяет метод HTTP для поиска подходящих методов действий.

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

В рассматриваемом примере запрос GET приведет в результате к выбору между GetAllReservations() и GetReservation(), но также бы подошли имена методов наподобие DoGetReservation() или даже ThisIsTheGetAction().

Чтобы принять решение, какой из этих двух методов действий выбрать, контроллер просматривает аргументы, которые они принимают, и с помощью переменных маршрутизации находит наилучшее соответствие. В случае запроса URL вида /api/reservation нет никаких переменных маршрутизации за исключением controller, поэтому выбирается метод GetAllReservations(), т.к. он не принимает аргументов.

При запросе URL вида /api/reservation/3 предоставляется значение для необязательной переменной сегмента id, что приведет к выбору метода GetReservation(), потому что он принимает аргумент id. Остальные действия в контроллере API ориентированы на другие HTTP-методы: POST, DELETE и PUT. Это основа для стиля REST (Representation State Transfer — передача состояния представления) средства Web API, чаще называемого службой, поддерживающей REST, когда операция указывается путем комбинирования URL и метода HTTP, используемого для ее запрашивания.

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

Отображение методов HTTP на методы действий

Ранее было указано, что базовый класс ApiController использует метод HTTP для выяснения, на какие методы действий направлять запросы. Это хороший подход, но он означает применение неестественных имен методов, которые не соответствуют соглашениям об именовании, используемым в остальных частях приложения. Например, метод PutReservation() мог бы иметь более естественное имя UpdateReservation(). Мало того, что имя UpdateReservation() делает очевидным назначение этого метода (обновить заявку на бронирование), но оно может также обеспечить более прямое отображение между действиями в контроллере и методами в хранилище.

Читать еще:  Docker сборка контейнера

У вас может возникнуть соблазн унаследовать класс хранилища от ApiController и открыть методы хранилища напрямую как Web API. Настоятельно рекомендуется не поступать так, а создавать отдельный контроллер, даже если он настолько же прост, как в рассматриваемом примере. В какой-то момент методы, которые вы хотите предоставлять через Web API, станут идти вразрез с возможностями хранилища, и наличие отдельного класса контроллера API упростит управление этим.

Web api frist сбора данных


Самым актуальный способом создать REST сервис в стеке технологий Майкрософт на сегодняшний день является ASP.NET Web API. До того эта технология значилась как WCF Web API и больше по названию тяготела к WCF. Но уже тогда там использовались сходные походы как в ASP.NET MVC, включая роутинг (routing). До нее существовали такие вещи как WCF 4 REST, WCF REST Starter Kit 3.5. Их все еще можно встретить на старых проектах и stackoverflow пестрит вопросами о них. Но то что ASP.NET Web API используется на новых проектах, а некоторые старые конвертируются, чтобы его использовать – радует. Так как предшественники были хуже как в плане технологии (приходилось писать много boilerplating code), удобства использования так и документации.

В предыдущих постах были рассмотрены некоторые теоретические аспекты REST – теперь создадим простой REST сервис с помощью Web API и рассмотрим ключевые элементы такого сервиса.
Начать стоит с подключения NuGet packages (и/или установки ASP.NET MVC):

  1. Web API, в случае если хостимся в ASP.NET:AspNetWebApi
  2. Self-hosted Web API:AspNetWebApi.Selfhost
  3. HttpClient включая XML и JSON форматеры:System.Net.Http.Formatting
  4. JsonValue для навигации и манипуляции JSON:System.Json

В нашем случае, мы создадим просто сервис, который хостится на ASP.NET MVC, а также посмотрим на принцип создания интеграционных тестов к нему, которые будут поднимать self-hosted REST сервис в тестовом контексте. Акцент на Data access layer делятся не будет, если в процессе вам необходимо прикрутить DAL, например, с использованием Entity Framework Code First, то я писал об одном из возможных подходов раньше.

Перед тем как создавать такой сервис необходимо также понимать что использовать Web API стоит если есть тесная связка с веб-клиентом, если сервис содержит логику выходящую за рамки CRUD операций. Если же у вас сервис по сути своей поставщик данных, т.е. операции в основном CRUD, то лучше использовать WCF Data Services, так как там много вещей из коробки генерится под базу — и CRUD операции и нормальная поддержка OData и IQuerable (в ASP.NET Web API она ограничена), которые позволяют делать запросы к сервису и данным с помощью Uri и специального OData синтаксиса.

Итак преступим. Для начала создадим новый проект ASP.NET MVC4:

Изображение 1
Естественно темплейт (шаблон) для MVC 4 нагенерит нам типичную структуру ASP.NET MVC проекта (файл ValuesController я уже успел переименовать на DocumentsController). Отличие в дополнительном контроллере для Web API. По умолчанию это ValuesController, естественно его необходимо переименовать.

Изображение 2

В нашем случае он стал DocumentsController. Из темплейта этот контроллер содержит операции заглушки для Get, Post, Put, Delete. В просто случае переопределим эти операции для DocumentsController и ресурса Document. Получится вот такой вот контроллер:

Это простой вариант, и здесь не используются фильтры для обработки сообщений или dependency resolvers. В свою очередь IDocumentRepository реализовано как простая заглушка и если дальше развивать тему с нормальным доступом к данным то реализацию можно подставить любую.
Теперь проверим операции. Это сделать можно используя Fiddler и правильно сформировав запрос. Например операция получения всех документов, используем адрес http://127.0.0.1:81/api/documents/. Используется стандартный роутинг из коробки:

Итак, запрос на http://127.0.0.1:81/api/documents/ должен вызвать метод IEnumerable Get() :

Так и есть, нам вернулся список в виде XML из двух элементов. Теперь попробуем content negotiation из коробки в действии. К тому же самому вызову добавим HTTP заголовок – Accept:application/json. Итак запрос:

Ответ ожидаем в Json:

Из коробки идут два стандартных форматера – XML и Json, но есть возможность добавлять свои.

Аналогичным образом будут работать остальные операции. Единственное попробуем еще запросить документ с недействительным идентификатором. Будем вызывать метод Document Get(string id) по адресу http://127.0.0.1:81/api/documents/9505a3b549b54881b3ed83fc19510534, где 9505a3b549b54881b3ed83fc19510534 – недействительный идентификатор, изменили последнюю цифру.

Ожидается ответ 404 NotFound. Результат запроса:


Вот таким вот образом можно создать и протестировать на работоспособность простенький REST сервис на базе ASP.NET Web API.

Основные концепты — ApiController

Так как мы имеем дело с REST сервисом. То из всего этого добра нас интересуют на начальном этапе контроллеры и роутинг. Контроллеры для Web API REST сервиса наследуются от от класса ApiController, который в свою очередь от интерфейса IHttpController. И ApiController несет с собой много добра, кроме конечно того что она автоматом распознается и выполняется. Из всего этого добра самое интересное являются свойства Request и Configuration.

Изображение 3

Основные концепты – Routing (Роутинг)

При вызове операций с контроллера важный момент играет routing. Именно routing позволяет подсистеме WebApi связать Uri адрес и конкретную операцию из контроллера. Причем есть несколько вариантов — либо операция-action помечается атрибутом, либо используется договоренность именовать операции с префиксом – Http Verb. Например, в методе PostDocument – именно префикс Post позволяет сказать Web Api что эта операция связанна с Uri и вызывается по соответствующему адресу с HTTP Verb – POST.
Еще одним вариантом для того, чтобы помочь выделить среди методов контроллера операции, которые связанны с URL – использование атрибутов — HttpGet, HttpPut, HttpPost, или HttpDelete, каждый из них соответствует такому же HTTP Verb – GET, PUT, POST, DELETE. Для того, чтобы навесить на операцию больше чем один HTTP Verb, или операцию отличную от 4 базовых (GET, PUT, POST, DELETE), используется атрибут – AcceptVerbs. Использование атрибутов также дает возможность отказаться от конвенции именования методов, когда префиксом выступает HTTP Verb.

Изображение 4

А для того чтобы избежать мапинга (mapping) метода как action используется атрибут NonAction без параметров.
Есть еще способ роутинга, когда каждый мапинг делается по средством атрибутов на метод, а не глобальным роутингом через Global.asax.cs, но о нем позже, так как он не стандартный. Хотя на этапе WCF Web API использовался именно он.

Routing по-умолчанию в Web API устанавливается как в методе RegisterRoutes на изображении 5 ниже. При использовании такого routing необходимо придерживаться конвенции именования методов в контроллере, когда каждый метод начинается с HTTP Verb префикса.

Ну и естественно важная часть маппинга – routing в Global.asax.cs:

Изображение 5

Соответственно под роутинг «api//» подпадают URLs и примерные имена методов:
Можно также сделать роутинг по имени action. Он не создается по-умолчанию темплейтом проекта. Например:
В случае с таким роутингом необходимо использовать атрибуты HttpGet, HttpPut, HttpPost, HttpDelete или AcceptVerbs чтобы указать на какие методы мапить . В WCF WebAPI использовался роутинг с помощью атрибутов, его тоже можно прикрутить, но об этом отдельно.

Основные концепты — HttpResponseMessage, HttpRequestMessage

По сути это два спец класса которые используются достаточно часто. Они нужны для того чтобы иметь возможность оперировать запросом и ответом. HttpRequestMessage можно получить через свойство Request от ApiController (Изображение 6). Tак как Web API контроллеры всегда наследуются от ApiController, то его можно получить в середине любого из наших контроллеров. HttpRequestMessage позволяет нам управлять запросом, например извлекать из него данные из HTTP Body либо HTTP Headers которые нам нужны.

Изображение 6

HttpResponseMessage можно создать, чтобы вернуть результат, либо просто Response код (Изображение 7), либо еще и с нагрузкой, запаковав в его свойство Content, нужный нам HttpContent, например для бинарных данных подойдет наследник от HttpContent – StreamContent. Из свойства Request можно вычитать бинарные данные документа, который пришел с клиента:

Изображение 7

Возврат ошибок — HttpResponseException

Вернуть ответ с ошибкой можно как с помощью HttpResponseMessage, указав код ошибки, так и с помощью специального класса HttpResponseException. Например, на изображении 7 на клиент возвращается ошибка InternalServerError = 500 с коротким описанием. Описание умеют читать далеко не все клиенты или клиентские библиотеки (были проблемы с iPad), в таком случае в тело сообщения с ошибкой можно писать объект более детально описывающий проблему, например свой кастомный объект с сообщением и кодом ошибки.

Хостинг

Само собой разумеется, что Web API REST сервис может хоститься на IIS либо вместе с ASP.NET MVC клиентом либо раздельно. Также его можно легко захостить вместе с ASP.NET MVC Web Role в облаке на Windows Azure. Но интересно, что Web API также можно хостить у себя в приложении, в памяти. Это значительно расширяет круг сценариев, в которых Web API может использоваться. Например с self-hosted Web API можно легко делать интеграционные тесты, которые поднимут во время тестирования self-hosted Web API сервис.

Читать еще:  Методы сбора вторичной информации

Например, на изображение 8 ниже, показано как поднимается с self-hosted Web API сервис для интеграционного теста в методе BecauseOf.

Изображение 8

Клиент

Клиентов к Web API REST может быть большое множество – есть куча библиотек под разные платформы для REST, можно обращаться к REST сервису c веб страницы по средством JavaScript и jQuery, можно использовать “старенький” класс WebClient для десктоп клиента. Вместе с Web API новым для .NET является также новый HttpClient, который очень легко использовать с десктоп клиента или тестового сценария (пример на изображении 8 метод should_make_tivial_get), и к тому же он изначально спроектирован асинхронным.

Результаты поиска « код вставки виджета »

Описание API

Инструменты

Методы API — Webhooks

Примеры

Методы API — Пользователи

Методы API — События

Методы API — Оплаты от юрлиц

Методы API — Заказы

Методы API — Словари

Методы API — Организации

Структура запроса

Пример запроса к API, выдающего 20 ближайших событий в Москве и Санкт-Петербурге:

Разберём по частям.

https:// — доступ к API возможен только по https, при попытке получения данных через http выдаётся ошибка 400 . Это позволяет гарантировать целостность данных и предотвратить пересылку любой критичной информации в незашифрованном виде.

api.timepad.ru/v1 — API Таймпада располагается на отдельном домене, в адрес встроено версионирование. Это сделано для того, чтобы если когда-либо появится v2, переход на неё будет опционален, а первая версия продолжит функционировать, пока у неё будут клиенты.

/events — ресурс событий, один из главных ресурсов API. С его помощью можно получить доступ к базе данных лекций, семинаров, концертов, конференций, сборов и встреч, проводимых через Таймпад, отфильтровав одним из нескольких десятков возможных способов.

.json — указание на желаемый формат данных. Поддерживается json и html. Если ничего не указано, API определяет формат автоматически: html в браузере, json во всех остальных случаях.

?limit=20&skip=0 — параметры деления на страницы (пагинации). В данном случае означает «20 событий, начиная с первого».

&cities=Москва,Санкт-Петербург — ограничение выдачи списком городов. Фильтр по городам — один из многих доступных для применения. Полный список в интерактивной документации.

&fields=location — список дополнительных полей, которые нужно вывести. Возможные значения можно посмотреть в интерактивной документации.

&sort=+starts_at — сортировка по дате начала события в порядке увеличения. Возможно также сортировать по нескольким другим параметрам.

Выбор выводимых полей

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

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

В результате такого запроса помимо полей по умолчанию также будут вставлены объект места проведения события и объект дополнительных данных о статусе регистрации на событие. Внутренние объекты или полностью не выводятся, или полностью выводятся, поле fields на их содержимое не влияет.

Список полей, которые можно вывести, можно найти в интерактивной документации с пометкой Optional, как на скриншоте:

Сортировка значений

API Таймпада поддерживает сортировку по одному из следующих полей:

name
starts_at
city
referrer_percent
created_at
id

Название поля сортировки нужно указать в запросе, например:

Чтобы сортировать по убыванию, нужно указать — перед названием поля, например:
https://api.timepad.ru/v1/events?sort=-id

При сортировке по возрастанию, можно опционально указать плюс перед названием, например,

Пагинация

Любые списки в API разделены на страницы. Для управления ими есть следующие параметры:

limit — количество элементов, которые нужно вернуть
skip — количество элементов, которые нужно пропустить

При этом ответ выглядит так:

В total отражается общее количество элементов в выборке, а в values находятся элементы, соответствующие настройке пагинации.

Пустые поля

API по-умолчанию убирает из результатов поля с пустыми значениями (пустые массивы, пустые строки, null). В случае, когда вам требуеются пустые значения, нужно указать параметр show_empty_fields со значением true

Create Web API for CRUD operation — Part 1

Here we will create a new Web API project and implement GET, POST, PUT and DELETE method for CRUD operation using Entity Framework.

First, create a new Web API project in Visual Studio 2013 for Web express edition.

Open Visual Studio 2013 for Web and click on File menu -> New Project.. This will open New Project popup as shown below.

Create Web API Project

In the New Project popup, select Web template under Visual C#. Enter project name WebApiDemo and the location where you want to create the project. Click OK to continue. This will open another popup to select a project template. Select Web API project as shown below.

Select Web API Project Template

Here, we are not going to use any authentication in our demo project. So, click on Change Authentication button to open Authentication popup and select No Authentication radio button and then click OK as shown below.

Change Authentication

Now, click OK in New ASP.NET Project popup to create a project as shown below.

Web API Project

As you can see, a new WebApiDemo project is created with all necessary files. It has also added default ValuesController. Since, we will be adding our new Web API controller we can delete the default ValuesController.

Here, we are going to use Entity Framework DB-First approach to access an existing school database. So, let’s add EF data model for the school database using DB First approach.

Add Entity Framework Data Model

To add EF data model using DB-First approach, right click on your project -> click New Item.. This will open Add New Item popup as shown below.

Create Entity Data Model

Select Data in the left pane and select ADO.NET Entity Data Model in the middle pane and enter the name of a data model and click Add. This will open Entity Data Model Wizard using which you can generate Entity Data Model for an existing School database. Download EF 6 demo project with Schoold Database from Github. The scope of the topic is limited to Web API so we have not covered how to generate EDM. Learn how to create Entity Data Model in EF 6.

EntityFramework will generate following data model after completing all the steps of Entity Data Model Wizard.

Generated Entities in the EDM Designer

Entity Framework also generates entities and context classes as shown below.

.edmx in the Project

Now, we are ready to implement CRUD operation using Entity Framework in our Web API project. Now, let’s add a Web API controller in our project.

Add Web API Controller

To add a Web API controller in your MVC project, right click on the Controllers folder or another folder where you want to add a Web API controller -> select Add -> select Controller. This will open Add Scaffold popup as shown below.

Create Web API Controller

In the Add Scaffold popup, select Web API in the left pane and select Web API 2 Controller — Empty in the middle pane and click Add. (We select Empty template as we plan to add action methods and Entity Framework by ourselves.)

This will open Add Controller popup where you need to enter the name of your controller. Enter «StudentController» as a controller name and click Add as shown below.

Create Web API Controller

This will add empty StudentController class derived from ApiController as shown below.

We will implement GET, POST, PUT and DELETE action methods in this controller in the subsequent sections.

Add Model

We will be accessing underlying database using Entity Framework (EF). As you have seen above, EF creates its own entity classes. Ideally, we should not return EF entity objects from the Web API. It is recommended to return DTO (Data Transfer Object) from Web API. As we have created Web API project with MVC, we can also use MVC model classes which will be used in both MVC and Web API.

Here, we will return Student, Address and Standard from our Web API. So, create StudentViewModel, AddressViewModel and StandardViewModel in the Models folder as shown below.

Models

The followings are model classes.

Now, let’s implement Get methods to handle various HTTP GET requests in the next section.

Создание вашего первого веб API с помощью MVC 6¶

HTTP служит не только для обработки веб страниц. Это также мощная платформа для создания API, который работает с сервисами и данными. HTTP является простым, подвижным и часто используется всеми и везде. Фактически у все платформ есть HTTP библиотеки, так что HTTP сервисы могут достичь разных клиентов, включая браузеры, мобильные устройства и традиционные десктоп-приложения.

Читать еще:  Сбор ценовой информации

В этой статье мы создадим простой веб API для управления списком “to-do”. Здесь вы не будете создавать какой-либо UI.

В предыдущие версии ASP.NET был включен фреймворк Web API для создания API. В ASP.NET 5 этот функционал был включен в MVC 6 фреймворк. Объединение этих двух фреймворков упрощает создание приложений, которые включают в себя UI (HTML) и API, поскольку у них один и тот же код и поток.

Если вы переносите приложение Web API на MVC 6, посмотрите Переход от ASP.NET Web API 2 в MVC 6

Вы можете просмотреть или скачать исходный код для этого примера на GitHub.

Общий обзор¶

Вот API, который вы создадите:

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

  • Клиент — это тот, кто “потребляет” веб API (браузер, мобильное приложение и тд). В этой статье мы не показываем клиентскую часть.
  • model — это объект, который представляет данные в приложении. В данном случае единственной моделью является элемент to-do. Модели представлены как простые C# классы (POCO).
  • controller — это объект, который обрабатывает HTTP запросы и создает HTTP ответы. В этом приложении будет один контроллер.
  • Чтобы не усложнять приложение, мы не будем использовать базу данных. Вместо этого элементы to-do будут храниться в памяти. Но мы все же включим простой слой данных, чтобы вы увидеть, что веб API и слой данных разделены. Если вы хотите увидеть пример, в котором используется база данных, просмотрите Создание первого MVC 6 приложения.

Установка Fiddler¶

Этот шаг не обязателен, но рекомендуется.

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

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

Запустите Visual Studio 2015. Из меню File выберите New > Project.

Выберите шаблон ASP.NET Web Application. Назовите проект TodoApi и нажмите OK.

В диалоговом окне New Project выберите Web API под ASP.NET 5 Preview Templates. Нажмите OK.

Добавление модельных классов¶

Модель — это объект, который представляет данные в вашем приложении. В данном случае единственной моделью у нас является элемент to-do.

Добавьте папку “Models”. В Solution Explorer кликните правой клавишей мышки по проекту. Выберите Add > New Folder. Назовите папку Models.

Вы можете вставлять модельные классы в любое место вашего проекта, но по соглашению мы используем папку Models.

Далее, добавьте класс TodoItem . Кликните правой клавишей мышки по папке Models и выберите Add > New Item.

В диалоговом окне Add New Item выберите шаблон Class. Назовите класс TodoItem и нажмите OK.

Замените сгенерированный код следующим:

Добавление классов репозитория¶

repository — это объект, который вмещает в себя слой данных и содержит логику для получения данных и отправки их сущности модели. Хотя в примере мы не используем базу данных, вам будет полезно увидеть, как внедрять репозитории в контроллеры. Создайте код для репозитория в папке Models.

Мы начнем с определения интерфейса репозитория ITodoRepository . Используйте шаблон Add New Item > Class.

Этот интерфейс определяет базовые CRUD операции. На практике у вас могут быть методы, определенные доменом.

Далее, добавьте класс TodoRepository , который реализует ITodoRepository :

Соберите приложение, чтобы увидеть, что никаких ошибок у вас нет.

Регистрация репозитория¶

При определении интерфейса репозитория мы можем отделить класс репозитория от MVC контроллера, который его использует. Вместо восстановления TodoRepository внутри контроллера, мы внедрим ITodoRepository с помощью DI контейнера ASP.NET 5.

Такой подход помогает нам более хорошо проводить модульное тестирование приложения. Юнит-тесты должны содержать “mock” или “stub” версии ITodoRepository . Тогда тест нацелен на логику контроллера, а не на слой данных.

IЧтобы внедрить репозиторий в контроллер, мы должны зарегистрировать его с помощью DI контейнера. Откройте файл Startup.cs. Добавьте следующую директиву using:

В метод ConfigureServices добавьте выделенный код:

Добавление контроллера¶

В Solution Explorer кликните правой клавишей мышки по папке Controllers. Выберите Add > New Item. В диалоговом окне Add New Item выберите шаблон Web API Controller Class. Назовите класс TodoController .

Замените сгенерированный код следующим:

У нас получился пустой класс для контроллера. В следующем разделе мы добавим методы для реализации API. Атрибут [FromServices] говорит MVC, чтобы он внедрил ITodoRepository , который был зарегистрирован в классе Startup .

Удалите файл ValuesController.cs из папки Controllers. В шаблон он добавлен как пример контроллера, но он нам не нужен.

Получение элементов to-do¶

Чтобы получить элементы to-do, добавьте следующие методы в класс TodoController .

Эти методы реализуют GET:

Вот пример HTTP ответа для метода GetAll :

Дальше я покажу вам, как просмотреть HTTP ответ с помощью инструмента Fiddler.

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

Атрибут [HttpGet] говорит о том, что мы работаем с методами HTTP GET. URL для каждого метода выглядит вот так:

  • Берем шаблонную строку в роутовом атрибуте контроллера: [Route(«api/[controller]»)]
  • Меняем “[Controller]” именем контроллера, котрое является именем класса контроллера минус суффикс “Controller”. В данном примере именем контроллера будет “todo”. Имя класса контроллера — это TodoController. В ASP.NET MVC имена не чувствительны к регистру.
  • Если в [HttpGet] атрибуте также есть строка шаблона, ее нужно добавить к пути. В данном примере мы эту строку не используем.

В методе GetById “” является переменной-заменителем. В действующем HTTP запросе клиент будет использовать ID элемента todo . Во время запуска, когда MVC вызывает GetById , он присваивает значение “” URL параметру метода id .

Откройте файл srcTodoApiPropertieslaunchSettings.json и замените значение launchUrl , чтобы здесь использовался контроллер todo . Тогда IIS Express вызовет контроллер todo после запуска проекта.

Возвращение значений¶

Метод GetAll возвращает объект CLR. MVC автоматически сериализует объект в JSON и записывает JSON в тело сообщения ответа. Кодом ответа для в данном случае является 200, и мы предполагаем, что тут нет необработанных исключений. (Необработанные исключения передаются как ошибки 5xx.)

В отличии от этого метод«GetById« возвращает более общий тип IActionResult . Это происходит потому, что у GetById есть два возвращаемых типа:

  • Если ни один элемент не обладает запрашиваемым ID, метод возвращает ошибку 404. Это происходит с помощью HttpNotFound .
  • Иначе метод возвращает 200 с телом ответа JSON. Это делается с помощью ObjectResult.

Использование Fiddler для вызова API¶

Этот шаг не обязателен, но вам будет полезно посмотреть на сырые HTTP ответы из веб API. В Visual Studio нажмите ^F5, чтобы запустить приложение. Visual Studio запускает браузер и переходит к http://localhost:port/api/todo , где port — это случайно выбранный номер порта. Если вы используете Chrome, Edge или Firefox, будут отображены данные todo. Если вы используете IE, IE предложит вам открыть или сохранить файл todo.json.

Запустите Fiddler. В меню File снимите галочку с Capture Traffic. Это отключит HTTP трафик.

Выберите страницу Composer. Во вкладке Parsed наберите http://localhost:port/api/todo , где port — это номер порта. Нажмите Execute, чтобы отправить запрос.

Результат появится в списке сессий. Ответ должен быть 200. Используйте вкладку Inspectors, чтобы просмотреть контекст ответа.

Реализация других CRUD операций¶

Наконец, нам нужно добавить в контроллер методы Create , Update и Delete . Я покажу вам различия в этих методах.

Create¶

Это метод HTTP POST, обозначенный атрибутом [HttpPost]. Атрибут [FromBody] говорит MVC, что он должен получить значение элемента to-do из тела HTTP запроса.

Метод CreatedAtRoute возвращает ответ 201, и это стандартный ответ для метода HTTP POST, который создает новый ресурс на сервере. CreateAtRoute также добавляет в ответ заголовок Location. Заголовок Location указывает URI нового элемента to-do. См. 10.2.2 201 Created.

Мы можем использовать Fiddler, чтобы отправлять и создавать запросы:

  1. На странице Composer выберите из выпадающего меню POST.
  2. В текстовое поле для заголовка запроса добавьте заголовок Content-Type со значением application/json . Fiddler автоматиески добавит заголовок Content-Length.
  3. В текстовое поле для тела запроса введите:
  4. Нажмите Execute.

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

Update¶

Update похож на Create , но использует HTTP PUT. Ответом является 204 (No Content). В соответствии с HTTP спецификацией, запрос PUT требует, чтобы клиент отправлял обновленные данные. Чтобы поддерживать частичные обновления, используйте HTTP PATCH.

Delete¶

Ответом является 204 (No Content). Это обозначает, что клиент получает 204, даже если элемент уже был удален или никогда не существовал. Есть два способа удалить ресурсы:

  • “Delete” обозначает “удалить существующий элемент”, а если элемент не существует, то вернуть 404.
  • “Delete” обозначает “элемента нет в коллекции.” Так что ответом будет 204.

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

Дальнейшие шаги¶

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

Информацию по публикации приложения вы можете получить тут: Публикация и размещение .

Ссылка на основную публикацию
Adblock
detector