#api

Подход №1: URL

Добавление номера версии в URL является очень распространенной практикой среди популярных публичных API.

По сути, вы просто добавляете v1 или 1 в URL, потому указать следующую версию не составит труда.

https://api.example.com/v1/places`
GET https://api.example.com/users/v1/users
/v1/users

Однажды вы получаете email от example.com, в котором говорится, что их API v1 через три месяца больше не будет поддерживаться

Плюсы

• Невероятно прост для API разработчиков

• Невероятно прост для API пользователей

• Удобные для URLы для копипаста

Минусы

• Технически не является RESTful

• Сложен при размещении на отдельные сервера

• Принуждает пользователей API прибегать к сложным и непонятным действиям для поддержания ссылок (links) в актуальном состоянии.

Подход №2: Имя хоста

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

https://api-v1.example.com/places

Плюсы

• Невероятно прост для API разработчиков

• Невероятно прост для API пользователей

• Удобные для URLы для копипаста

• Простое использование DNS для распределения версий на несколько серверов.

Минусы

• Технически не является RESTful

• Принуждает пользователей API прибегать к сложным и непонятным действиям для поддержания ссылок (links) в актуальном состоянии.

Подход №3.1: Тело и параметры запроса

Если вы решили уйти от размещения версии в URI, тогда одно из двух других мест, где её можно указать, это само тело HTTP запроса.

POST /places HTTP/1.1
Host: api.example.com
Content-Type: application/json
{
    "version": "1.0"
}

Некоторые предполагают, что решение этой проблемы в том, чтобы перемести параметр версии в строку запроса, но тогда версия снова попадает в URL! И тогда сразу многие проблемы первых двух подходов возвращаются.

POST /places?version=1.0 HTTP/1.1
Host: api.example.com

header1,header2
value1,value2

Популярные API

• Netflix

• Google Data

• PayPal

• Amazon SQS

Плюсы

• Прост для API разработчиков

• Прост для API пользователей

• URL остается таким же, когда параметр внутри тела запроса

• Технически это больше похоже на RESTful, чем указывание версии в URI

Минусы

• Различные виды Content-type требуют различные параметры и для некоторых (например CSV) такой вариант просто не подходит.

• Принуждает пользователей API прибегать к сложным и непонятным действиям для поддержания ссылок (links) в актуальном состоянии, если параметр версии находится в строке запроса

• незя GET выполнить

Подход №3.2: Кастомный заголовок запроса

Итак, если URL или тело HTTP запроса не очень подходящее место для размещения информации о версии API, то что остается? Конечно, это заголовки!

GET /places HTTP/1.1
Host: api.example.com
BadApiVersion: 1.0

Это плохо и не правильно по многом причинам. Почему?

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

HTTP/1.1 200 OK  
BadAPIVersion: 1.1  
Vary: BadAPIVersion

С другой стороны, промежуточные кеши могут отдать клиентам неверный ответ. (например, ответ 1.2 на клиент 1.1 или наоборот)

Без указания заголовка Vary, возникают трудности с системами кеширования, например Varnish не сможет понять, что кто-то запрашивает версию 1.0, потому что URL не сильно отличается от запроса версий 1.1 или 2.0. Это может стать большой проблемой, поскольку пользователи API запрашивают конкретную версию, а не какую-то другую.

Плюсы

• Прост для пользователей API (если они знают про заголовки)

• URL остается таким же

• Технически это больше похоже на RESTful, чем указывание версии в URI

Минусы

• Системы кеширования могут запутаться

• Разработчики API могут запутаться (если они не знают про заголовки)

• для клиентов - плохой вариант

Подход №4: Распределение контента

Заголовок Accept спроектирован для того, чтобы попросить сервер выдать ответ для определенного ресурса в определенном формате. Традиционно, многие разработчики задумываются о нем только в случае (X)HTML, JSON

GitHub до сих пор следует советам многих людей, упомянутых в этой главе, и используют заголовок Accept для отдачи различных типов данных.

Все типы данных GitHub выглядят примерно так:

application/vnd.github[.version].param[+json]

Самые базовые типы, которые поддерживает API:

application/json

application/vnd.github+json

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

Популярные API

• GitHub

Плюсы

• Прост для пользователей API (если они знают про заголовки)

• URL остается таким же

• HATEOAS-совместимый

• Кеш-совместимый

• Sturgeon-approved (нуу.. наверно "осетр одобряе")

Минусы

• Разработчики API могут запутаться (если они не знают про заголовки)

• Версионирование целиком всего API может запутать пользователей (но и все другие походы имеют туже проблему)

• клиентские тоже не будут работать