Post #797

Вопросы дизайна и проектирования сильнее связаны с проектированием API, чем мы привыкли думать. В конце концов, и то, и другое — это интерфейсы и взаимодействие. Проектировщик интерфейсов строит диаграмму переходов между экранами, и, как правило, на одном экране есть какое-то главное действие (+ несколько второстепенных). Изменение экранов, их состояний, переходы с одного экрана на другой — это и есть смена тех самых состояний, которые упоминаются в принципе stateless. Less — это из на сервере нет, а на клиенте они как раз есть, от них всё и проектируется. Изменяется экран — изменяется и состояние. Каждый переход — вызов API. Один и тот же артефакт служит основой и для работы дизайнера, и для работы проектировщика API. Но и это не всё. Каждый дизайнер знает про аффорданс — свойство вещи "предлагать" или "подсказывать" способ её использования. Вы возьмете молоток за рукоятку, а не за головку, потому что самой своей формой она "предлагает" вам это. В интерфейсах аффорданс играет большую роль, акцентируя внимание пользователя на элементах взаимодействия и предлагая определенные действия. Например, подчеркивание ссылок в гипертексте как бы предлагает вам нажать на них. Такое же "предложение" справедливо и для API. И — вы не поверите — называется HATEOAS, о котором писал Рой Филдинг! Почему-то на русском практически не встречается статей на эту тему, а для англоязычной аудитории это почти что общее место. Аффордансы в API — это предложения следующих действий с предоставленным ресурсом: следующий шаг в процессе, изменение свойств и состояний, удаление, в конце концов. Майк Амундсен называет проектирование вокруг аффордансов высшей точкой зрелости API. Ну а что они такое, конкретно? Да это же ссылки на действия с ресурсом из HATEOAS! Как это может выглядеть в коде: { "user_id": "12345", "username": "johndoe", "email": "[email protected]", "_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 построены совсем на других принципах. Возможно, эта ветка технологического развития так и не реализуется, как и многие другие перспективные, но не получившие массового применения технологии.