Проектирование REST API: частые ошибки и как их избежать

[Cordekk]

вообще возник серьезный вопрос по архитектуре Rest. Есть get запрос с большим количеством параметров, с ними возникают проблемы из-за слишком длинного URi. Как лучше поступить с точки зрения REST:

1) Завернуть параметры в json и передавать в тело GET запроса?

2) Завернуть параметры в json и передавать в тело POST?

[dopusteam]

С точки зрения здравого смысла не используйте get с телом :)

Явно оно вроде не запрещено в спецификациях, но на практике многие либы/инструменты не работают с телом в get

[Cordekk]

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

[dopusteam]

Почему бы просто post не использовать? Зачем делать два запроса? Плюс на сервере нужно будет вводить новую сущность, хранить ее, ...

[Cordekk]

Для "архитектурной чистоты"...

[dopusteam]

Скорее для бездумного следования REST подходу.
С точки зрения архитектуры вы только усложняете всё

[MaDeLa]

Лучше использовать POST с передачей фильтров в body.
GET с телом формально не запрещён стандартом разработки, но в реальности большинство прокси, кешей и даже часть HTTP-клиентов игнорируют или отбрасывают body, поэтому поведение получается нестабильным.
Для REST-совместимого решения обычно применяют POST, когда объём фильтров превышает безопасную длину URI.

[Cordekk]

про то, что Post применяется в запросах ресурса с передачей параметра через тело, я знаю. Вот Dadata.api как живой пример есть.

[MS70]

Ув. автор!
Товарищ в первом комментарии справедливо поинтересовался, боюсь, причина в том, что вы строго ограничили POST только созданием ресурса. Дело в том, что в официальной доке https://www.rfc-editor.org/rfc/rfc7231 создание стоит даже не на первом месте при перечислении функций, возлагаемых на него, и для решения проблемы с разросшимся GET его и надо использовать.

For example, POST is used for the following functions (among others):
Providing a block of data, such as the fields entered into an HTML form, to a data-handling process;

Так что вот эту часть стоило бы расширить:
"POST — создать,"

[MaDeLa]

Спасибо за замечание — абсолютно справедливо.
В статье мы ошибочно не сфокусировались на более широких CRUD-случаях. Добавили пометочку со звёздочкой. Вам респект за бдительность :)

[totsamiynixon]

20 лет прошло с момента диссертации Роя Филдинга, а разработчики до сих пор не могут отличить REST от HTTP RPC.

REST это про гипермедиа, HATEOAS, возможность задать поведение клиента с сервера. URL в REST это адрес ресурса и ключ кеширования, он вообще не обязан иметь какой-то четкой структуры. GET без body нужен, чтобы передавать все параметры запроса в строке запроса и иметь возможность закешировать ответ на любом из прокси, чтобы не читать body. PUT, PATCH, DELETE и тд являются вариациями POST (того же эффекта можно добиться используя POST и комбинации заголовков для манипуляции кешом на клиенте); именно поэтому в HTML 5 до сих пор есть только формы GET & POST.

А вы рассказываете про RPC поверх HTTP. И там хоть делайте хоть PATCH /orders хоть POST /update-order, скорее всего вы не будете использовать заголовки для кешироания в своих микросервисах и дадите клиенту вашего сервиса (разработчику) самому решать, что кешировать, а что нет. И уж тем более у вас не будет поддержки HATEOAS.

Рецепт такой - вы пишете веб интерфейс используя ASP.NET Core или NextJS (конечный потребитель это человек через браузер) - вы уже используете REST. Вы пишите микросервисы (конечный потребитель разработчики, которые интегрируют ваш АПИ в свои приложения) - вы используете RPC.

[MaDeLa]

Спасибо за развернутый комментарий. Вы поднимаете действительно фундаментальный момент: классический REST по Филдингу и то, что в индустрии обычно называют REST API - две разные вселенные.

В строгом REST HATEOAS является ключевым ограничением архитектуры и большинство современных API под это определение действительно не подпадают. По сути, то, что мы используем в микросервисах - это HTTP RPC c REST-like конвенциями уровня ресурсов, методов и кодов ответа.

Именно к этой практической модели и относится статья: она описывает типичные ошибки аналитиков и разработчиков в прикладных корпоративных API, в которых:

• HATEOAS практически никогда не применяется;

• кеширование чаще контролируется на уровне клиентской логики, а не прокси;

• URL используется как удобный идентификатор ресурса, а не как часть гипермедийного контракта.

Именно в таких условиях (корпоративные системы, интеграции между сервисами, работа аналитиков с backend-разработчиками) и возникают описанные в статье ошибки - от неправильного выбора HTTP-метода до отсутствия версионирвования.

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

Спасибо, что подсветили разницу. Возможно стоит вынести это в отдельный раздел, чтобы разделять уровни абстракции и не смешивать архитектурную идею с индустриальной реальностью.

[andozhskaya]

Хорошая статья. Не поняла, почему поставлены минусы за неё.