Wednesday, June 24, 2015

Что нужно учесть при разработке API

Preambule:
Как API разрабатывается в Гугле:
http://lanyrd.com/2010/io2010/smwf/

Оригинал
http://habrahabr.ru/post/181988/

Разработка web API перевод

Веб-разработка*, API*

Интро

Это краткий перевод основных тезисов из брошюры «Web API Design. Crafting Interfaces that Developers Love» Брайана Маллоя из компании Apigee Labs. Apigee занимается разработкой различных API-сервисов и консталтингом. Кстати, среди клиентов этой компании засветились такие гиганты, как Best Buy, Cisco, Dell и Ebay.

В тексте попадаются комментарии переводчика, они выделены курсивом.

Собираем API-интерфейсы, которые понравятся другим разработчикам

Понятные URL для вызовов API

Первый принцип хорошего REST-дизайна — делать вещи понятно и просто. Начинать стоит с основных URL адресов для ваших вызовов API.

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

/dogs для работы со списком собак
/dogs/12345 для работы с отдельной собакой

Существительные — это хорошо, а глаголы — плохо

Держите глаголы как можно дальше от базовых URL сущностей вашего API. Многие разработчки используют глаголы для описания объектов. Ясное дело, что в работе часто приходится моделировать сложные сущности. И эти сущности взаимодействуют между собой. Но при попытке ввести глаголы для моделирования сущностей и их связей, мы, скорее всего, получим большое количество труднозапоминаемых и непонятных вызовов:

/getAllDogs
/getAllLeashedDogs
/getDog
/newDog
/saveDog

Видите эти вызовы? Это ужас.

Вместо глаголов — HTTP

Мы только что описали собак с помощью двух базовых URL адресов с существительными. Теперь нам нужно работать с созданными сущностями. Чаще всего требуются операции чтения, создания, редактирования и удаления (CRUD — Create — Read — Update — Delete). Для этого нам прекрасно подойдут HTTP-методы GET, POST, PUT и DELETE.

POST /dogs — создать новую собаку
GET /dogs — получить список собак
PUT /dogs — редактирование всех собак сразу
DELETE /dogs — удаление всех собак

POST /dogs/12345 — вернуть ошибку (собака 12345 уже создана)
GET /dogs/12345 — показать информацию о собаке
PUT /dogs/12345 — редактировать собаку 12345
DELETE /dogs/12345 — удалить

Базовые URL выглядят просто, глаголы не используются, все интуитивно и понятно. Красота!

Множественное число

Хорошо использовать для описания базовых URL существительные во множественном числе. Хуже — в единственном числе. Плохо — смешивать адреса с существительными в единственном и множественном числе.

/checkins у Foursquare
/deals y GroupOn
/Product y Zappos

Конкретные имена лучше абстрактных

Абстрактные названия — это часто считается крутым у архитекторов API. И это совсем не круто для тех, кто потом с этим API будет работать.
/blogs, /videos, /news, /articles — это выглядит очевидным. А вот /items и /assets — нет.

Связи

Одни ресурсы всегдя связаны с другими ресурсами. Есть ли очевидный и простой способ показать эти связи через API? При этом помня о нашем разделении на существительные и глаголы?

GET /owners/5678/dogs
POST /owners/5678/dogs

Мы только что представили связь двух ресурсов в простом виде. Метод GET в этом случае вернет нам список собак владельца 5678, а метод POST — добавит владельцу 5678 еще одну собаку.
Связи очень удобно представлять в виде /ресурс/идентификатор/ресурс.

Сложные вещи нужно прятать за знаком «?»

Почти у каждого API есть куча параметров, которые можно читать, обновлять, фильтровать и работать с ними всякими другими способами. Но все эти параметры не должны быть видны в базовых адресах. Лучше всего указывать параметры внутри обращения к базовым адресам.

GET /dogs?color=red&state=running&location=park

А что насчет ошибок?

Хороший механизм обработки ошибок — это часть любого хорошего API. Давайте посмотрим, как выглядят ошибки в популярных API.

Facebook
HTTP Status Code: 200
{"type" : "OauthException", "message":"(#803) Some of the aliases you requested do not exist: foo.bar"}

Не важно, как выполнится запрос — Facebook всегда вернет нам код 200 OK.

Twilio
HTTP Status Code: 401
{"status" : "401", "message":"Authenticate","code": 20003, "more info": "http://www.twilio.com/docs/errors/20003"}

Twilio проделали хорошую работу и для каждой ошибки в API подобрали адекватный код ошибки HTTP. Как и Facebook, ребята предоставляют информацию об ошибке еще и в теле ответа. И, что самое прикольное, они дают ссылку на документацию по проблеме.

SimpleGeo
HTTP Status Code: 401
{"code" : 401, "message": "Authentication Required"}

SimpleGeo дают сообщение об ошибке в коде HTTP и снабжают его небольшим пояснением в теле ответа.

Используйте коды ответов HTTP

Смело берите HTTP коды ответов и сопоставляйте с ответами вашего API. Всего в частом употреблении находится около 70-ти кодов. Мало кто из разработчиков помнит их все, так что из этих 70-ти лучше взять примерно 10. Кстати, так поступает большая часть провайдеров API.

Google GData
200 201 304 400 401 403 404 409 410 500

Netflix
200 201 304 400 401 403 404 412 500

Digg
200 400 401 403 404 410 500 503

Какие коды ошибок HTTP стоит использовать?

Возможно только 3 варианта ответов API

Запрос прошел успешно
На вход были переданы неправильные данные — клиентская ошибка
Произошла ошибка при обработке данных — серверная ошибка

Так что можно взять за основу 3 кода ответов:

200 OK
400 Bad Request (некорректный запрос)
500 Internal server error (внутренняя ошибка сервера)

Если 3-х кодов вам недостаточно — возьмите еще 5:

201 Created (Запись создана)
304 Not Modified (Данные не изменились)
404 Not Found (Данные не найдены)
401 Unauthorized (Неавторизованный доступ)
403 Forbidden (Доступ запрещен)

Лучше всего не следовать этой практике слепо. Оценивайте пользу от использования HTTP кодов ответов
в каждом конкретном случае. Скорее всего, использование кодов ответов не везде будет оправданным и уместным. Например, если вы пишете бэкенд для небольшого веб-приложения — то легко можно ограничиться кодами ошибок в теле ответа. А еще стандартый ответ 200 OK позволит создать два механимза обработки ошибок: для ошибок сервера и для ошибок самого API. В общем — думайте, взвешивайте. А потом принимайте решение.

И, конечно же, при ошибке всегда нужно прикладывать сообщение для разработчиков. А приложить к сообщению ссылку на документацию по проблеме — это еще лучше.

Никогда не выпускайте API без указания версии

Twilio /2010-04-01/Accounts
salesforce.com /services/data/v20.0/sobjects/Account
Facebook ?v=1.0

Twilio требует при каждом запросе к API передавать время, когда приложение разработчика было скомпилировано. На основе этой даты Twilio определяет, какую версию API нужно предоставить приложению. Это умный и интересный подход, но слишком сложный. А еще можно легко запутаться с датами.

Salesforce.com вставляет v20.0 в середину адреса API запроса. И это очень хороший подход. Но не стоит использовать точку в нумерации версии — это провоцирует излишне частые изменения в интерфейсе API. Можно сколь угодно часто менять логику работы внутри API, но вот сами интерфейсы должны меняться максимально редко. Так что лучше обойтись без точки и не искушать себя.

Facebook тоже использует нумерацию версий в запросе, но прячет её в параметры запроса. И этот подход плох тем, что после очередного внедрения новой версии API все приложения, не передающие версию в запросе, начинают глючить.

Как реализовать версии в API?

Используйте префикс v, целые числа и располагайте номер версии в левой части адреса. Например, /v1/dogs.
Держите в рабочем виде как минимум одну предыдущую версию

Еще можно указывать версию в заголовках ответа сервера. Это может давать некоторые дополнительные возможности при работе с API. Но если вы используете множество разных версий и требуете обязательно указывать их в заголовках — это симптом большой проблемы.

Частичный ответ

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

Linkedin /people: (id, first-name, last-name, industry)
Facebook /joe.smith/friends?fields=id,name,picture
Google ?fields=title, media:group(media:thumbnail)

Перечислять необходимые поля через запятую в адресе запроса — это очень простой и удобный подход. Берите его на вооружение.

Сделайте простую паджинацию

Отдавать все записи по первому же запросу — очень плохая идея. Поэтому вы должны обязательно предусмотреть паджинацию. Давайте посмотрим, как в популярных API можно вытащить записи с 50 по 75.

Facebook: смещение 50 и лимит 25
Twitter: страница 3 и 25 записей на страницу
Linkedin: с 50-й записи прочитать 25

Мы рекомендуем использовать лимит и смещение. Этот подход более интуитивен.

/dogs?limit=25&offset=50

Еще стоит приложить к каждому ответу мета-информацию: текущая страница, сколько всего записей доступно.

Предусмотрите значения по умолчанию: если пользователь не передал в запросе параметры паджинации, считайте лимит равным 10 и смещение — равным 0 (вывести первые 10 записей).

А что насчет действий?

Не все API-ресуры являются записями, которые можно читать, редактировать и удалять. Бывают и API-действия. Переводы, вычисления, конвертации — все это действия.

Лучше всего для таких запросов использовать глаголы, а не существительные.

/convert?from=EUR&to=USD&amount=100

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

Поддержка нескольких форматов

Здорово поддерживать несколько форматов ответа.

Google ?alt=json
Foursquare /venue.json
Digg ?type=json

Кстати, Digg позволяет установить формат ответа и через HTTP-заголовок Accept.

Мы рекомендуем подход Foursquare.

/dogs.json
/dogs/1234.json

Еще можно предусмотреть ответы API не только в разных форматах, но и ответы для разных типов клиентов. Например, можно сделать API, способное работать одновременно с iOS-приложением и фронт-эндом веб-приложения. Это может выглядеть так: /dogs.ios и /dogs.web.

Формат по умолчанию

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

Названия атрибутов

Атрибуты можно называть разными способами.

Twitter created_at
Bing DateTime
Foursquare createdAt

Существует много конвенций именования переменных. Нам, как спецам по Ruby on Rails, конвенция Twitter близка по духу. Но лучшим подходом мы считаем подход Foursquare: — camelCase (переменные с маленькой буквы, классы — с большой). Такой способ именования наиболее симпатичен для подачи данных в JSON: данные выглядят похоже на JavaScript. Что, в общем, логично для JSON.

Хоть автор и советует почаще использовать camelCase, лучше все же подумать о клиенте и потом уже принимать решение. Например, с вашим API может общаться программа, написанная на C, а ей лучше использовать несколько_другую_конвенцию.

Поиск

Глобальный поиск оформить просто:

/search?q=search+word

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

/owners/5678/dogs?q=red

А чтобы представлять данные в разных форматах, мы вспомним о расширениях:

/search.xml?q=search+word

Соберите все API вызовы на одном домене

Facebook предоставляет два домена.

api.facebook.com этот адрес появился первым
graph.facebook.com этот адрес ввели после внедрения глобального графа

Foursquare ограничились одним адресом

api.foursquare.com

Twitter завели 3 адреса, 2 из которых ориентированы на посты и поиск

stream.twitter.com
api.twitter.com
search.twitter.com

Легко догадаться, как Facebook и Twitter завели себе по несколько адресов: проще направлять запросы в разные кластеры через DNS, чем через логику. Но мы делаем приятный API для разработчиков, поэтому опять выберем подход Foursquare.

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

Делайте редиректы

Если кто-то обращается к вашему API-домену и не передает никаких параметров — смело делайте редирект на домен с документацией для разработчиков. Заведите несколько интуитивно понятных доменов для документации и делайте редирект на основной домен разработчиков.

api.* -> developers.*
dev.* -> developers.*
developer.* -> developers.*

Коды HTTP ответов и исключения на клиенте

Как мы уже говорили ранее, лучше всего отправлять код ошибки не только в теле ответа API, но и в HTTP коде ответа. Но как быть, если клиент выбрасывает исключение при получении любого кода HTTP, отличного от 200? Для таких случаев ребята из Twitter предусмотрели блестящее и простое решение — добавлять параметр к запросу.

/public_timelines.json?suppress_response_code=true

В результате ошибки будут приходить с кодом 200.
Предусмотрите в своем API параметр suppress_response_codes и сделайте его равным true по умолчанию.

А что если клиент поддерживает ограниченный набор HTTP методов?

В таком случае нужно эмулировать полноценный REST API с помощью GET-параметров.

чтение /dogs
создание /dogs?method=post
редактирование /dogs/1234?method=put
удаление /dogs/1234?method=delete

Будьте аккуратны с таким подходом! Если вы будете неаккуратно обращаться с такими ссылками и не обеспечите им должной безопасности, боты (вроде поискового робота Google) могут вызывать такие ссылки. И вы получите бесконечно создающиеся и удаляющиеся записи при каждом заходе бота.

Авторизация

Этот вопрос сложный, и мы с моими коллегами никогда не можем прийти к согласию быстро. Давайте посмотрим, что делают ведущие игроки.

PayPal Permissions Service API
Facebook OAuth 2.0
Twitter 1.0a

Обратите внимание на то, что PayPal реализовали свою систему авторизации еще до того, как был изобретен OAuth.

Если вам требуется авторизация пользователей через сторонние приложения — только OAuth. И ни в коем случае не делайте что-то вроде OAuth, но «немного другое».

«Болтливые» API

«Болтливые» — это значит, что для выполнения популярных операций приходится выполнять 3-4 вызова API подряд. Это плохо.

Попробуйте посмотреть на ваши вызовы глазами пользователя. Вы увидите, что примерно 80% вызовов принимают и отдают данные одинаковой структуры. Это значит, что вполне можно сделать псевдонимы для последовательностей вызовов. После этого пользователь сможет единожды направить данные на вход, и вся цепочка вызовов выполнится сама.

Tuesday, June 23, 2015

Web API Authentication, Authorization

Forms Authentication using Web API

Download source - 4.7 MB

Introduction

With the advent of OWIN middleware and Identity framework, traditional forms authentication is outdated since OWIN middleware and Identity framework takes care of everything in a better and organized manner. But sometimes, existing applications cannot be migrated to Identity framework due to one or the other reason, but Form Authentication user login is needed. For such situations, here is the workaround.

Background

There was an existing ASP.NET application using role based forms authentication, and was supposed to be migrated to ASP.NET MVC, but for some reason, the client wanted to stick to forms authentication.

Using the Code

To implement forms authentication, interception of both request and response is required which is done with the help of DelegatingHandler.

Hide Shrink

Copy Code

public class BasicAuthMessageHandler : DelegatingHandler
    {
        private const string BasicAuthResponseHeader = "WWW-Authenticate";
        private const string BasicAuthResponseHeaderValue = "Basic";

        public adminPrincipalProvider PrincipalProvider = new adminPrincipalProvider();

        protected override System.Threading.Tasks.Task<HttpResponseMessage> SendAsync(
            HttpRequestMessage request,
            CancellationToken cancellationToken)
        {
            AuthenticationHeaderValue authValue = request.Headers.Authorization;
            if (authValue != null && authValue.Parameter != "undefined" && 
    !String.IsNullOrWhiteSpace(authValue.Parameter))
            {
                string email = authValue.Parameter;
                if (HttpContext.Current.Session == null || 
  HttpContext.Current.Session["userToken"] == null || 
  string.IsNullOrEmpty(HttpContext.Current.Session["userToken"].ToString()))
                {
                    HttpContext.Current.Session["userToken"] = email;
                }
                else
                {
                    email = HttpContext.Current.Session["userToken"].ToString();
                }

                if (!string.IsNullOrEmpty(email))
                {
                    IPrincipal principalObj = PrincipalProvider.createPrincipal(email, "Admin");
                    Thread.CurrentPrincipal = principalObj;
                    HttpContext.Current.User = principalObj;
                }
            }
            return base.SendAsync(request, cancellationToken)
               .ContinueWith(task =>
               {
                   var response = task.Result;
                   if (response.StatusCode == HttpStatusCode.Unauthorized
                       && !response.Headers.Contains(BasicAuthResponseHeader))
                   {
                       response.Headers.Add(BasicAuthResponseHeader
                           , BasicAuthResponseHeaderValue);
                   }
                   return response;
               });
        }
    }

Principal object is used to assign role to a validated user, this principal object is added to HttpContext's user property.

Controller Login & Logout Web Method

Hide Copy Code

       [HttpPost, AllowAnonymous, Route("login")]
        public async Task<HttpResponseMessage> Login([FromBody]LoginRequest request)
        {
            var loginService = new LoginService();
            LoginResponse response = await loginService.LoginAsync(request.username, request.password);
            if (response.Success)
            {
                FormsAuthentication.SetAuthCookie(response.Token, false);
            }
            return Request.CreateResponse(HttpStatusCode.OK, response);
        }

        [HttpPost, AllowAnonymous, Route("logout")]
        public void Signout()
        {
            FormsAuthentication.SignOut();

            if (HttpContext.Current.Session != null)
                HttpContext.Current.Session.Abandon();
        }

To setup role based authorization on webmethods, the following attributes are to be added on the top of webmethod's implementation.

Hide Copy Code

[HttpGet, Authorize(Roles = "admin"), Route("name")]

Calling from Client

The following jquery code shows how to make a Login call.

Hide Copy Code

$(document).ready(
    function () {
       $("#btnSubmit").click(function () {
          var usrname = $("#username").val();
          var pwd = $("#password").val();
          $.post("http://localhost:50750/api/loginctrl/login", 
  { username: usrname, password: pwd }, function (result) {
                    alert(JSON.stringify(result));
                });
                       
          });
        });

Registering Delegating Handler

Before starting the execution of the project, custom Delegating Handler is to be registered with Application's Message Handlers. In this app, Delegating handler is registered inside Global.asax's Application_Startmethod.

Hide Copy Code

 protected void Application_Start()
        {
            AreaRegistration.RegisterAllAreas();
            GlobalConfiguration.Configure(WebApiConfig.Register);
            FilterConfig.RegisterGlobalFilters(GlobalFilters.Filters);
            RouteConfig.RegisterRoutes(RouteTable.Routes);
            BundleConfig.RegisterBundles(BundleTable.Bundles);

            var basicAuthMessageHandler = new WebAPI_FormsAuth.Helper.BasicAuthMessageHandler();
            basicAuthMessageHandler.PrincipalProvider = 
   new WebAPI_FormsAuth.Helper.adminPrincipalProvider();
            //start message handler
            GlobalConfiguration.Configuration.MessageHandlers.Add(basicAuthMessageHandler);
        }

http://weblog.west-wind.com/posts/2013/Apr/18/A-WebAPI-Basic-Authentication-Authorization-Filter

ASP.NET MVC, Web API, SingleR (статья на русскком)

http://metanit.com/sharp/mvc/
http://professorweb.ru/my/ASP_NET/mvc/level8/8_2.php

Оригинал
http://regfordev.blogspot.ru/2012/06/rest.html#.VYkzlvntlBc

REST сервисы и ASP.NET Web API

Самым актуальный способом создать 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):

Web API, в случае если хостимся в ASP.NET: AspNetWebApi
Self-hosted Web API: AspNetWebApi.Selfhost
HttpClient включая XML и JSON форматеры: System.Net.Http.Formatting
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. Получится вот такой вот контроллер:

public class DocumentsController : ApiController

{

    private IDocumentRepository documentRepository;

    public DocumentsController()

    {

        documentRepository = new DocumentRepository();

    }

    public IEnumerable<Document> Get()

    {            

        return documentRepository.GetDocuments();            

    }

    public Document Get(string id)

    {

        try

        {

            return documentRepository.GetDocument(id);

        }

        catch (DocumentNotFoundException)

        {                

            throw new HttpResponseException(new HttpResponseMessage(HttpStatusCode.NotFound));

        }

    }

    public void Post(Document document)

    {

        try

        {

            documentRepository.CreateDocument(document);

        }

        catch (DocumentNotFoundException)

        {

            throw new HttpResponseException(new HttpResponseMessage(HttpStatusCode.NotFound));

        }

    }

    public void Put(Document document)

    {

        try

        {

            documentRepository.UpdateDocument(document);

        }

        catch (DocumentNotFoundException)

        {

            throw new HttpResponseException(new HttpResponseMessage(HttpStatusCode.NotFound));

        }

    }

    public void Delete(Document document)

    {

        documentRepository.DeleteDocument(document);

    }

}

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

public static void RegisterRoutes(RouteCollection routes)

{

    routes.IgnoreRoute("{resource}.axd/{*pathInfo}");

    routes.MapHttpRoute(

        name: "DefaultApi",

        routeTemplate: "api/{controller}/{id}",

        defaults: new { id = RouteParameter.Optional }

    );

    routes.MapRoute(

        name: "Default",

        url: "{controller}/{action}/{id}",

        defaults: new { controller = "Home", action = "Index", id = UrlParameter.Optional }

    );

}

Итак, запрос на http://127.0.0.1:81/api/documents/ должен вызвать метод IEnumerable<Document> 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/{controller}/{id}" подпадают URLs и примерные имена методов:

/api/contacts, 
GetAllContacts, PostNewContact

/api/contacts/1, 
GetContact, PutUpdatedContact, DeleteContact

Можно также сделать роутинг по имени action. Он не создается по-умолчанию темплейтом проекта. Например:

routes.MapHttpRoute(
    name: "ActionApi",
    routeTemplate: "api/{controller}/{action}/{id}",
    defaults: new { id = RouteParameter.Optional }
);

В случае с таким роутингом необходимо использовать атрибуты HttpGet, HttpPut, HttpPost, HttpDelete или AcceptVerbs чтобы указать на какие методы мапить {action}. В 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), и к тому же он изначально спроектирован асинхронным.

Выводы

ASP.NET Web API свежая и отличная технология для создания REST сервисов от Microsoft. До нее создавать сервисы было сложнее и требовалось больше boilerplating code. Среди интересных ее фишек – удобный content negotiation, возможность создавать self-hosted REST services, схожесть и хорошая интеграция с ASP.NET MVC. Основным концептами ASP.NET Web API являются широкие возможности хостинга (IIS в том числе на IaaS cloud services, self hosted, Windows Azure), роутинг, обработка request,response и ошибок, хорошая тестируемость как юнит тестами так и интеграционными тестами, content negotiation с удобным механизмом форматеров.

Ссылки по теме

http://www.asp.net/web-api
Куча материалов для старта. Видео туториалы и статьи.

http://webapibloggers.com/
Агрегатор блогов по Web API