В конце концов, и то, и другое — это интерфейсы и взаимодействие.
Проектировщик интерфейсов строит диаграмму переходов между экранами, и, как правило, на одном экране есть какое-то главное действие (+ несколько второстепенных). Изменение экранов, их состояний, переходы с одного экрана на другой — это и есть смена тех самых состояний, которые упоминаются в принципе stateless. Less — это из на сервере нет, а на клиенте они как раз есть, от них всё и проектируется. Изменяется экран — изменяется и состояние. Каждый переход — вызов API. Один и тот же артефакт служит основой и для работы дизайнера, и для работы проектировщика API.
Но и это не всё. Каждый дизайнер знает про аффорданс — свойство вещи "предлагать" или "подсказывать" способ её использования. Вы возьмете молоток за рукоятку, а не за головку, потому что самой своей формой она "предлагает" вам это. В интерфейсах аффорданс играет большую роль, акцентируя внимание пользователя на элементах взаимодействия и предлагая определенные действия. Например, подчеркивание ссылок в гипертексте как бы предлагает вам нажать на них.
Такое же "предложение" справедливо и для API. И — вы не поверите — называется HATEOAS, о котором писал Рой Филдинг! Почему-то на русском практически не встречается статей на эту тему, а для англоязычной аудитории это почти что общее место.
Аффордансы в API — это предложения следующих действий с предоставленным ресурсом: следующий шаг в процессе, изменение свойств и состояний, удаление, в конце концов. Майк Амундсен называет проектирование вокруг аффордансов высшей точкой зрелости API. Ну а что они такое, конкретно? Да это же ссылки на действия с ресурсом из HATEOAS!
Как это может выглядеть в коде:
{
"user_id": "12345",
"username": "johndoe",
"email": "john.doe@example.com",
"_links": {
"self": {
"href": "/users/12345",
"methods": ["GET", "PUT", "DELETE"]
},
"update_profile": {
"href": "/users/12345/profile",
"methods": ["PUT"],
"expected_fields": ["first_name", "last_name", "address"]
},
"change_password": {
"href": "/users/12345/password",
"methods": ["PUT"],
"expected_fields": ["old_password", "new_password"]
}
}
} Так мы можем работать практически без документации! Идея пришла из простого следования HTML: там же сразу есть гиперссылки, и человек может нажимать на них, не запрашивая дополнительной информации и не обращаясь к документации. Вот бы и в API так делать! Ничего не вышло, т.к. c API работает программа, которую создает программист, и ей не требуются все эти ссылки, она сама не принимает решения ходить по ним. Это должен сделать программист. А дополнительный трафик они жрут порядочно.
Но теперь у нас есть кому ходить по ссылкам — ИИ-агентам. В этой связи я бы ожидал возврата интереса к HATEOAS, но пока мы его не видим. Те же MCP и A2A построены совсем на других принципах. Возможно, эта ветка технологического развития так и не реализуется, как и многие другие перспективные, но не получившие массового применения технологии.