Какие контракты используют в REST?

Контракты и принципы RESTful API

В REST (Representational State Transfer) не существует формальных «контрактов» в виде жестких спецификаций, как, например, в SOAP с его WSDL. Однако REST основывается на набор фундаментальных принципов и соглашений, которые формируют неявный «контракт» между клиентом и сервером. Эти принципы обеспечивают единообразие, простоту и масштабируемость взаимодействия.

1. Использование HTTP методов (HTTP Verbs)

Это ключевой контракт: каждый метод HTTP соответствует определенной операции над ресурсом.

GET    /api/users      # Получить список пользователей
POST   /api/users      # Создать нового пользователя
PUT    /api/users/{id} # Полностью обновить пользователя (или создать)
PATCH  /api/users/{id} # Частично обновить пользователя
DELETE /api/users/{id} # Удалить пользователя

Строгое соблюдение семантики методов — основа REST. Например, GET никогда не должен изменять состояние ресурса.

2. Ресурсы и URI (Uniform Resource Identifier)

Ресурсы представляются в виде уникальных идентификаторов (URI). Контракт заключается в структуре URI:

• Иерархичность: /api/orders/{orderId}/items
• Отсутствие действий в URI: Вместо /api/users/createUser используется POST /api/users.
• Использование подресурсов для связей.

3. Статусы HTTP (HTTP Status Codes)

Это стандартизированный способ сообщения результатов операций. Клиент и сервер «контрактно» соглашаются на интерпретацию кодов:

• 2xx (Успех): 200 OK, 201 Created, 204 No Content.
• 4xx (Ошибка клиента): 400 Bad Request, 404 Not Found, 409 Conflict.
• 5xx (Ошибка сервера): 500 Internal Server Error.

4. Форматы представления данных (Representations)

Ресурс может быть представлен в разных форматах. Контракт определяется через HTTP заголовки:

• Content-Type: Указывает формат данных от сервера (например, application/json).
• Accept: Заголовок клиента, указывающий ожидаемый формат (Accept: application/json).

Пример тела ответа в JSON (наиболее популярный формат):

{
    "id": 123,
    "name": "Иван Петров",
    "email": "ivan@example.com"
}

5. Гипермедиа (HATEOAS - Hypermedia As The Engine Of Application State)

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

{
    "id": 123,
    "name": "Иван Петров",
    "_links": {
        "self": { "href": "/api/users/123" },
        "orders": { "href": "/api/users/123/orders" }
    }
}

Это позволяет клиенту динамически «переходить» по API без жесткой привязки к заранее известным URI.

6. Статусность (Statelessness)

Жесткий контракт: каждый запрос должен содержать всю необходимую информацию для его обработки. Сервер не хранит состояние клиента между запросами (сессии). Авторизация, например, осуществляется через токен в каждом запросе (Authorization: Bearer <token>).

Дополнительные соглашения (Best Practices)

• Версионирование API: Часто реализуется через URI (/api/v1/users) или заголовки (Accept: application/vnd.myapi.v1+json).
• Фильтрация, сортировка, пагинация: Используются query parameters для унификации:

  GET /api/users?page=2&limit=10&sort=name&filter=active
  

• Стандартизация ошибок: Общая структура для всех ошибок 4xx/5xx.

{
    "error": {
        "code": "USER_NOT_FOUND",
        "message": "Пользователь с указанным ID не существует",
        "details": {}
    }
}

Контракт в Go: практическая реализация

В Go RESTful API часто строятся с использованием стандартной библиотеки net/http или фреймворков (Gin, Echo). Контракты соблюдаются через четкое определение маршрутизации и обработчиков.

Пример минимального handler с соблюдением контрактов:

package main

import (
    "encoding/json"
    "net/http"
    "strconv"
)

type User struct {
    ID   int    `json:"id"`
    Name string `json:"name"`
}

var users = map[int]User{1: {ID: 1, Name: "Test User"}}

// GET /api/users/{id}
func getUserHandler(w http.ResponseWriter, r *http.Request) {
    if r.Method != http.MethodGet {
        w.WriteHeader(http.StatusMethodNotAllowed) // Контракт метода
        return
    }

    idStr := r.PathValue("id") // Используем PathValue (Go 1.22+)
    id, err := strconv.Atoi(idStr)
    if err != nil {
        w.WriteHeader(http.StatusBadRequest) // Контракт кода ошибки
        return
    }

    user, exists := users[id]
    if !exists {
        w.WriteHeader(http.StatusNotFound) // Контракт кода ошибки
        return
    }

    w.Header().Set("Content-Type", "application/json") // Контракт формата
    w.WriteHeader(http.StatusOK)
    json.NewEncoder(w).Encode(user) // Контракт представления (JSON)
}

Таким образом, «контракты» в REST — это совокупность принципов архитектуры, стандартов HTTP и общепринятых практик, которые обеспечивают надежное, понятное и единообразное взаимодействие между распределенными компонентами системы. Их соблюдение критически важно для создания качественных, поддерживаемых и легко интегрируемых API.