Web API 2 в ASP.NET

Введение в Web API 2

Данное руководство устарело. Актуальное руководство: Руководство по ASP.NET Core

Web API представляет иной способ построения приложения ASP.NET несколько отличный от ASP.NET MVC. Web API представляет собой веб-службу, которая может взаимодействовать с различными приложениями. При этом приложение может быть веб-приложением ASP.NET, либо может быть мобильным или обычным десктопным приложением.

Также надо отметить, что платформа Web API 2 не является частью фреймворка ASP.NET MVC и может быть задействована как в связке с MVC, так и в соединении с Web Forms. Поэтому в Web API имеется своя система версий. Так, первая версия появилась с .net 4.5. А вместе с .NET 4.5.1 и MVC 5 вышла Web API 2.0.

Чтобы разобраться в работе веб-служб Web API создадим простое шаблонное приложение. При создании нового проекта укажем в качестве шаблона Web API:

Стандартный проект Web API после создания будет выглядеть как обычный проект mvc 5 с небольшими модификациями:

По умолчанию в папке Contollers уже будет два контроллера: стандартный контроллер HomeController и контроллер - ValuesController, который и реализует функционал Web API:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Net;
using System.Net.Http;
using System.Web.Http;

namespace WebApiApp.Controllers
{
    public class ValuesController : ApiController
    {
        // GET api/values
        public IEnumerable<string> Get()
        {
            return new string[] { "value1", "value2" };
        }

        // GET api/values/5
        public string Get(int id)
        {
            return "value";
        }

        // POST api/values
        public void Post([FromBody]string value)
        {}

        // PUT api/values/5
        public void Put(int id, [FromBody]string value)
        {}

        // DELETE api/values/5
        public void Delete(int id)
        {}
    }
}

Определение контроллера Web API отличается от обычного контроллера MVC. Во-первых, основной функционал сосредоточен, главным образом, а пространстве имен System.Web.Http, поэтому оно подключается в начале файла.

Во-вторых, он является наследником класса ApiController, который никак не связан с базовым классом контроллеров для MVC - Controller

В-третьих, контроллеры Web API применяют стиль REST (Representation State Transfer или "передача состояния представления").

REST-архитектура предполагает применение следующих методов или типов запросов HTTP для взаимодействия с сервером:

• GET

• POST

• PUT

• DELETE

• PATCH

В контроллере ValuesContoller нет стандартных методов действий, которые возвращают ActionResult, как в обычных контроллерах. Определенные в контроллере Web API методы сопоставляются с одноименными методами HTTP.

Маршрутизация в Web API

Другой особенностью проекта Web API является наличие файла WebApiConfig.cs (в папке App_Start), который содержит определения маршрутов Web API:

public static class WebApiConfig
{
    public static void Register(HttpConfiguration config)
    {
        // Web API configuration and services

        // Web API routes
        config.MapHttpAttributeRoutes();

        config.Routes.MapHttpRoute(
            name: "DefaultApi",
            routeTemplate: "api/{controller}/{id}",
            defaults: new { id = RouteParameter.Optional }
        );
    }
}

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

В итоге обращение api/values будет соответствовать обращению к контроллеру ValuesCotroller, причем почти ко всем действиям сразу (кроме Get(int id) - так как в данном случае необходим еще идентификатор, например api/values/2)

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

Так, например, запрос GET api/values будет сопоставлен с методом IEnumerable<string> Get() и вернет в ответ браузеру коллекцию элементов string. В то же время если в GET-запросе будет передан параметр api/values/7, то данному запросу будет соответствовать метод string Get(int id), так как он принимает параметр.

Если же сервер получит запрос PUT с адресом api/values, то такой запрос будет сопоставлен с методом Put.

Чтобы задействовать маршрутизацию Web API, в файле Global.asax в метод Application_Start() добавляется следующая строка: GlobalConfiguration.Configure(WebApiConfig.Register);

Условности при наименовании методов

При создании методов контроллера Web API действует некоторые условности. Так, имена методов по умолчанию должны начинаться с имени предназначенного для них метода HTTP. В случае с контроллером по умолчанию все просто: все методы действий носят названия методов HTTP.

Но нам необязательно жестко придерживаться этих условностей, и мы можем использовать любые другие имена без префиксов. Правда, в этом случае нам надо будет явно указать метод HTTP в виде атрибута, например:

public class ValuesController : ApiController
{
	public IEnumerable<string> GetAllItems()
    {
        return new string[] { "value1", "value2" };
    }

    public string GetItem(int id)
    {
        return "value";
    }

	[HttpPost]
    public void CreateItem([FromBody]string value)
    {}

    [HttpPut]
    public void EditItem(int id, [FromBody]string value)
    {}

    [HttpDelete]
    public void RemoveItem(int id)
    {}
}

Таким образом, если первые два действия соответствуют соглашениям об именовании (в начале содержат название метода HTTP), то к остальным мы применяем атрибуты, чтобы система знала, с каким методом надо сопоставлять запрос.