Какой API можно назвать RESTful?

Что такое RESTful API?

RESTful API — это интерфейс программирования приложений, который следует принципам архитектурного стиля REST (Representational State Transfer), предложенного Роем Филдингом в 2000 году. Такой API проектируется как набор ресурсов, доступ к которым осуществляется через стандартные HTTP-методы, а взаимодействие строится на безсостоянии (stateless), единообразии интерфейса и других ключевых ограничениях REST.

Ключевые принципы RESTful API

1. Единообразие интерфейса (Uniform Interface)

Это фундаментальный принцип, включающий:

• Идентификация ресурсов: каждый ресурс имеет уникальный URI (например, /api/users/123).
• Манипуляция ресурсами через представления: клиент взаимодействует с ресурсом через его представление (например, JSON или XML), передавая его в теле запроса или получая в ответе.
• Самодостаточные сообщения: каждый запрос содержит всю информацию, необходимую для его обработки.
• Гипермедиа как двигатель состояния приложения (HATEOAS): ответы API содержат ссылки на связанные ресурсы, позволяя клиенту динамически исследовать API.

2. Отсутствие состояния (Stateless)

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

// Пример Stateless аутентификации в заголовке запроса
[HttpGet("profile")]
public IActionResult GetProfile()
{
    var token = Request.Headers["Authorization"].ToString();
    // Проверка токена для каждого запроса
}

3. Кэширование (Cacheability)

Ответы сервера должны явно указывать, можно ли кэшировать данные и как долго. Это улучшает производительность и масштабируемость.

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: max-age=3600

4. Клиент-серверная архитектура

Четкое разделение ответственности: клиент отвечает за пользовательский интерфейс, сервер — за хранение данных и бизнес-логику.

5. Слоистая система (Layered System)

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

6. Код по требованию (Code on Demand, опционально)

Сервер может временно расширять функциональность клиента, передавая исполняемый код (например, JavaScript).

Критерии RESTful API на практике

Использование HTTP-методов по назначению

• GET: получение ресурса или коллекции (идемпотентный, безопасный).
• POST: создание нового ресурса.
• PUT: полное обновление ресурса (идемпотентный).
• PATCH: частичное обновление ресурса.
• DELETE: удаление ресурса (идемпотентный).

// Пример RESTful контроллера в ASP.NET Core
[ApiController]
[Route("api/[controller]")]
public class ProductsController : ControllerBase
{
    [HttpGet] // GET /api/products
    public IActionResult GetAll() { ... }
    
    [HttpGet("{id}")] // GET /api/products/5
    public IActionResult GetById(int id) { ... }
    
    [HttpPost] // POST /api/products
    public IActionResult Create(Product product) { ... }
    
    [HttpPut("{id}")] // PUT /api/products/5
    public IActionResult Update(int id, Product product) { ... }
    
    [HttpDelete("{id}")] // DELETE /api/products/5
    public IActionResult Delete(int id) { ... }
}

Ресурсо-ориентированные URI

URI должны отражать ресурсы (существительные), а не действия (глаголы):

• ✅ /api/orders/123/items (ресурс "элементы заказа")
• ❌ /api/getOrderItems?orderId=123 (глагол в URI)

Использование HTTP-статусов

• 200 OK: успешный запрос.
• 201 Created: ресурс создан.
• 204 No Content: успешно, но без тела ответа.
• 400 Bad Request: ошибка клиента.
• 404 Not Found: ресурс не существует.
• 500 Internal Server Error: ошибка сервера.

Форматы данных

• JSON как основной формат обмена данными.
• Поддержка Content Negotiation через заголовок Accept.

// Поддержка разных форматов в ASP.NET Core
[HttpGet("{id}")]
[Produces("application/json", "application/xml")]
public ActionResult<Product> GetById(int id)
{
    var product = _repository.GetProduct(id);
    return product != null ? Ok(product) : NotFound();
}

Отличия RESTful API от RPC-стиля

Пример HATEOAS в RESTful API

{
  "id": 123,
  "name": "John Doe",
  "email": "john@example.com",
  "_links": {
    "self": { "href": "/api/users/123" },
    "orders": { "href": "/api/users/123/orders" },
    "update": { "href": "/api/users/123", "method": "PUT" },
    "delete": { "href": "/api/users/123", "method": "DELETE" }
  }
}

Заключение

API можно назвать RESTful, если он последовательно применяет все ограничения REST, особенно единообразие интерфейса и HATEOAS. На практике многие API, называющие себя RESTful, реализуют только часть принципов (часто опуская HATEOAS), что корректнее называть HTTP API или REST-like API. Истинно RESTful API позволяет клиенту динамически обнаруживать возможности через гипермедиа-ссылки, что делает его более гибким и эволюционно устойчивым. В экосистеме .NET для создания таких API идеально подходит ASP.NET Core Web API с его встроенной поддержкой маршрутизации, форматирования ответов и соглашений REST.