Привет!

Внезапный "а знаете ли вы пост?".

Наверняка вы слышали, что при проектировании REST API необходимо отдавать предпочтение стандартизированный штукам, например для авторизации использовать заголовок Authentication.

Чего вы, возможно, не слышали (по крайней мере я не слышал до вчерашнего дня) - ответы на запросы с заголовком Authentication запрещено кэшировать по умолчанию. А если использовать доморошенные заголовки, то надо не забыть явно запретить кэширование ответов.

#http_api@ergonomic_code #rest_api@ergonomic_code #posts@ergonomic_code

Привет

Сегодня у нас рубрика "Мои факапы".

Есть у меня один проект, где флоу создания одной из сущностей такой:
1) непривилегированный пользователь создаёт сущность
2) привилегированный пользователь её одобряет или отклоняет

ну и плюс привилегированный пользователь может её редактировать в любой момент.

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

В итоге сейчас у нас есть метод PATCH /entity/{id}
который принимает сущность с 15 нуллабельными полями. используется двумя способами - либо присылаются все 15, либо 1 - approved

И есть метод POST /entity
С теми же 15 полями. но не нуллабельными.

И хз что с этим добром теперь делать.

Щяс я уже думаю, что надо было не выпендриваться, обновление делать через PUT, а аппрув через PATCH /entity/{id}/approved или POST /entity/{id}/(approve|reject)

А от PATCH-а сущностей держаться подальше до тех пор, пока требования к стенке не припрут - в языках со статической типизацией это боль

И заодно наткнулся на прикольную штуку JSON-P - когда мне придётся в следующий раз делать патч, я так пойду, а не через типизированную нуллабельную ДТОшку

#case@ergonomic_code #project_camp@ergonomic_code #http_api@ergonomic_code #rest_api@ergonomic_code #tools@ergonomic_code

Привет!

Зацените чё накапал я ненавижу и работать с АПИ в виде сваггера (оно почти всегда не работает полностью) и уш тем более писать его - пихать в код гору аннотаций для доков к сваггеру, где соотношение сигнал шут 1 к 2 - то ещё удовольствие.

И сам я предпочитаю писать доки на Spring Rest Docs - и собственно текст доков можно нормально писать, и примеры гарантированно рабочие. Но многие привыкли таки к сваггеру и хотят его. А с этим тулом, кажется, можно разом обоих зайцев убить.

#docs@ergonomic_code #spring@ergonomic_code #http_api@ergonomic_code #rest_api@ergonomic_code

Привет!

Я тут вынашиваю страшный план - отказаться от REST-стиля в "бэке одного фронта".

Как я собираюсь это делать:
1) Ядро продолжать так же делать из подсистем-объектов
2) Вокруг ядра сделать слой app, где по конторллеру на каждую страницу/экран/вью
3) урлы будут вида /api/app/login-page/login, api/app/dashboard-page/get-init-data
В общем в некотором смысле вернуться к структуре из этого поста, но сервисы приложения смёржить с контроллерами. Ну либо к пакетированию по компонентам Брауна

Что надеюсь получить:
1) Упростить процесс проектирования. Я давно этим занимаюсь и прочитал пачку книг по РЕСТу, но всё равно буквально в каждом проекте вылазит какая-нибудь штука, над которой я долго грею голову
2) снизить сцепленность ядра. в моём текущем подходе зачастую в подсистему надо тащить зависимость на другую подсистему, только для того чтобы вытащить вложенную сущность для какой-нить админки
3) Повысить удобство для фронтендеров - у них постоянно возникают вопросы что откуда брать для данной конкретной страницы. Тут, надеюсь, не будет. Плюс в доках появится понятное место куда можно будет сиквенс диаграммы работы страницы воткнуть
4) Повысить производительность. Как засунуть в рест один запрос для формы ввода, который вернёт пачку справочников для выпадающего списка - я не очень понимаю. А в эту схему - очень понимаю

Что потеряю и как планирую нивелировать потери
1) идиоматичность. С РЕСТом в целом народ как-то уже разобрался, а тут опять какая-то непонятная хрень. Это я попробую нивелировать за счёт простоты, возможности перенести общие принципы проектирования и постами с описанием идеи и кейсов
2) универсальность. Новому клиенту может не подойти существующее АПИ. Для второго клиента можно будет завести свой набор методов, а для третьего уже спроектировать и прикрутить сверху REST апи

Пока не очень понимаю что делать с методами, которые нужны на разных страницах. Но есть несколько идей:
1) по факту дублировать эндпоинты для них с минимизацией дублирования кода через делегирование в Котлине (и кстати о Котлине - я последнее время работаю с .net и чёт прям устал от NullPointerException - хочу назад в налло-безопстность 😥)
2) оставить такие методы в ядре
3) завести понятие ui-компонента на бэке - урлы вида /api/app/image-component/load

Я пока ещё думаю на эту тему и не уверен, что пойду туда, но возможно в ближайшем времени опробую её на личном проекте. И если опробую - расскажу как впечатления:)

#http_api@ergonomic_code #rest_api@ergonomic_code #ergo_approach@ergonomic_code

Привет!

Проснулись? Похмелились?:) Вот вам линко пост потупить в кровати, пока раскачиваетесь:) С прошедшим:)

Подвернулась под руку хорошая статья по дизайну REST API. Там никаких откровений, но в одном месте и кратко собрана вся ключевая информация о том, как проектировать хорошие API.

#posts@ergonomic_code #http_api@ergonomic_code

Привет!

У нас тут на проекте случилась поучительная история про REST, плюс посмотрел
REST next level: Crafting domain-driven web APIs by Julien Topçu @ Spring I/O 2023 - по мотивам всего этого накатал очередной микропост - что-то я разошёлся в этом месяце:)

#talks@ergonomic_code #http_api@ergonomic_code #rest_api@ergonomic_code

Привет!

С подачи Романа Русакова запоем прочитал The API.
Очень крутая книга, рекомендую.
Роман - спасибо:)

Так же вы, возможно, задаётесь вопросом что это я затих.
Вряд ли, конечно, но я всё равно отвечу - лопачу джиру Проект Э:)
Чтобы понять стоило ли оно того. Джира, у нас, к сожалению, не в лучшем состоянии и я не большой специалист по её анализу, поэтому идёт тяжко и в зависимости от методики результат получается от хрен на хрен, до 10х улучшения. Но что радует - нигде нет просадки ни по одной метрике.

Сейчас я вроде собрал методику, которая должна дать более-менее вменяемые цифры, которые, я надеюсь сойдутся к 1.5х снижению трудозатрат и 2х снижению кол-ва багов.
Осталось доразмечать 517 задач:)

#books@ergonomic_code #http_api@ergonomic_code

Привет!

А вы знали, что оказывается есть стандарт на тела ошибочных JSON-ответов - Problem Details for HTTP APIs и для него в 6-ой Spring завезли поддержку?

#http_api@ergonomic_code #spring@ergonomic_code #error_handling@ergonomic_code

Но не Jackson сегодня гвоздь программы.

Я накатал микропост о том как стремление улучшить HTTP API проекта (который был "готов" 1.5 недели назад) привело к улучшению дизайна его модели.

#http_api@ergonomic_code #rest_api@ergonomic_code #project_mariotte@ergonomic_code