UI Design Principles¶

Описание¶

Работа пользовательского интерфейса с сущностями системы во многих случаях сводится к набору типовых операций:

• Получение списка сущностей, возможно, с фильтрацией и заданием лимитов
• Получение данных для сущности
• Создание новой сущности
• Редактирование сущности: Как одного поля, так и всех полей в целом
• Удаление сущности

В результате анализа мы пришли к выводу, что в разных частях интерфейса одна и та же сущность может быть представлена в нескольких видах:

• id, текст -- для combobox
• набор редактируемых полей - для формы редактирования.
• сжатая информация - для всплывающих подсказок.
• Расширенная информация, включающая в себя и часть связанных сущностей - карточки объекта и так далее.

В связи с этим было решено ввести в API такое понятие как View - фактический вид сущности. В информационных запросах View должен быть частью пути url по двум причинам:

• FastAPI не поддерживает роутинг по querystring
• Для каждого View тип response отличается кардинально. Делать несколько типов ответов и объединять их через Union - крайне плохой вариант, так как пользователь API не будет заранее знать, в каком виде ему ожидать ответ. Делать один тип ответа с большинством полей в Optional - еще более худший вариант, так как тогда у пользователя вообще не будет понимания, в каком случае может быть заполнено конкретное поле.

Предлагается принять соглашение о следующем наборе view:

• default - вид по умолчанию (если не задан). Если не определен, использовать preview
• label - для комбобоксов - id + метка + стиль + иконка (если есть)
• short - короткий preview для комбобоксов, если не определен, используется preview
• preview - просмотр
• full - самый расширенный вариант, если не определен, использовать preview.
• form - форма редактирования
• secret - показать credentials?

Предлагается следующая иерархия URL

• GET /api/ui/<сущность>?<filter> - список сущностей (результат сформатирован для view default)
• GET /api/ui/<сущность>/v/<view>?<filter> - список сущностей (результат сформатирован для заданного view)
• GET /api/ui/<сущность>/<id> - данные для сущности с (результат сформатирован для view default)
• GET /api/ui/<сущность>/<id>/v/<view> - данные для сущности с (результат сформатирован для заданного view)
• POST /api/ui/<cущность> - создать новый объект.
• PUT /api/ui/<сущность>/<id>/v/<view> - редактировать объект с заданным набором полей
• DELETE `/api/ui/<сущность>/ - удаление объекта

  То есть вводится дополнительный классификатор-суффикс:

  • /v/<view> - использовать формат <view>
  • /a/<action> - запуск дополнительного действия для объекта

  Открытые вопросы¶

  • Завязывать ли POST на view?