ASP.NET Core Web API. Основные термины

При работе c ASP.NET Core Web API мы будем использовать различные термины и определения, касающиеся каких-то моментов при разработке Web API, например, такие термины как ресурс, HTTP-глагол и т.д. Рассмотрим эти термины.

REST

Довольно часто встречающаяся аббревиатура. Согласно википедии, REST (от англ. Representational State Transfer — «передача репрезентативного состояния» или «передача «самоописываемого» состояния») — архитектурный стиль взаимодействия компонентов распределённого приложения в сети. То есть это некий свод согласованных правил и принципов, которым должна соответствовать система (API).

По тому, что считать REST API, а что не считать написано довольно много статей (причем, не всегда совпадающих в ключевых моментах). Например, здесь указывается, что соответствие какого-либо API принципам REST не означает, что такой API использует протокол HTTP, а здесь — указывается, что основным блоком REST сервисов является протокол HTTP.

Оставим эти «философские» вопросы теоретикам от программирования и договоримся, что, когда речь заходит о REST, то мы говорим об архитектурном стиле и тот факт, что в ASP.NET Core основным транспортом является протокол HTTP никак не связано с этим термином.

RESTful API

Еще одно определение, вызывающее нешуточные споры, связанные, в первую очередь с тем, что считать REST API. Опять же для дальнейшего изучения темы ASP.NET Core Web API возьмем самое простое определение того, что такое RESTful API:

RESTful API — это API спроектированный в соответствии с основными принципами REST. Всего выделяется шесть принципов, пять из которых должны быть реализованы:

1. Клиент-серверная архитектура
2. Stateless (сервер не хранит информацию о сессии с клиентом)
3. Кэширование
4. Единообразие интерфейса
5. Слоистая архитектура (Layered system)
6. Код по требованию (Code on demand) — дополнительный принцип, соблюдение которого не обязательно.

Как эти принципы можно реализовать на практике — посмотрим далее.

Ресурс  

Ресурс — ключевое определение проектировании API. Под термином «ресурс» понимается всё, к чему будет иметь доступ клиент API. Это может могут быть любые данные, объекты и даже сервисы. Например, если мы говорим о какой-либо сущности в нашем проекте (объекте C#, коллекции объектов и т.д.), к которому клиент API будет иметь доступ, то этот объект в терминах проектирования API является ресурсом.

Например, мы разрабатываем API для списка задач. В этом случае, мы можем описать ресурс API (задачу) на языке C# как объект следующего класса:

public class TaskResource
{
    public int Id { get; set; } 
    public string Name { get; set; }
    public string Description { get; set; }
    public DateTime Deadline { get; set; }
}

Представление ресурса

Клиент и сервер обмениваются представлениями ресурсов. Для нас, на практике, это означает следующее — ресурсы API должны быть каким-либо образом сериализованы. По умолчанию, в ASP.NET Core Web API используется сериализация в JSON. Однако это не означает того, что, мы не можем выбрать в качестве формата обмена данными, например, XML или вообще plain text.

Если мы захотим получить информацию о какой-либо задаче, то сервер отправит нам, например, такое представление ресурса в формате JSON:

{
  "id": 1,
  "name": "Задача",
  "description": null,
  "deadline": "2024-01-01T00:00:00"
}

Вне зависимости от выбранного формата, клиент API должен знать все схемы представления ресурсов API. Схемы ресурсов указываются в документации к API. Например, схема ресурса TaskResource, может выглядеть в документации следующим образом:

По такому описанию можно определить, какие типы данных используются для свойств, могут ли свойства иметь значение null и т.д. В ASP.NET Core Web API для документирования API используется Swagger, что значительно облегчает нам работу над проектом в целом.

Идентификатор ресурса

Любой ресурс API должен иметь свой уникальный идентификатор, который также носит название URI (Uniform Resource Identifier).

Чтобы получить доступ к задаче с Id = 1, пользователь должен будет использовать URI ресурса, например, такой:

http://example.com/tasks/1или такой http://example.com/tasks/id1

Какая форма URI будет выбрана для представления ресурсов — зависит от разработчиков. На этом моменте может возникнуть вопрос: почему мы говорим про URI, а по факту, выше представлены URL (uniform resource locator)? Опять же, чтобы не было путаницы в дальнейшем: согласно RFC 3305, URL — это тип URI, который идентифицирует ресурс через представление его основного механизма доступа. Поэтому строку http://example.com/tasks/1 мы можем называть и URI и URL. Главное для нас, что эта строка будет являться уникальным идентификатором ресурса API.

HTTP-глаголы

HTTP-глаголы определяют, какой тип операции будет выполняться над ресурсом. Второе название HTTP-глаголов — HTTP-методы (GET, PUT, POST, DELETE и т.д.). При проектировании API мы НЕ должны для каждого метода, применяемого к ресурсу определять свой идентификатор. Например, если мы хотим получить объект задачи, то мы должны обеспечить выполнение следующего запроса пользователем:

GET /tasks/1 HTTP/1.1
Host: example.com

Если хотим удалить задачу, то запрос должен быть:

DELETE /tasks/1 HTTP/1.1
Host: example.com

но не таким:

DELETE /delete-tasks/1 HTTP/1.1
Host: example.com