Comments 11
Отличная статья! Спасибо автору, все разложено по пунктам и довольно ясно описано.
Хороший материал. Для начинающих и мидлов самое то)
Необходимо определить свои соглашения об именовании — в частности, «политику регистров», чтобы все ресурсы использовали единообразный стиль написания.
Совершенно верно. Поэтому очень бросается в глаза когда вы в своей статье используете то "GET", то "Get", то "POST", то "Delete", то "PATCH".
И хотел бы спросить про параметры запроса. Встречал в интернете вариант при котором параметры посылаются POST запросом в формате JSON. Насколько это корректный вариант?
POST по согласованию используется для создания. Все запросы идут через uri для выборки. Если вам нужны условия для получения данных, в том числе и пагинация и фильтрация, то только GET. Эта практика существует с каменного века ЧПУ (человекопонятный урл, а не станок) и mod_rewrite в Apache
Вы другой вариант вовсе не рассмотрели.
Для создания можно использовать и PUT.
А использование GET приводит к тому что код и логика становятся не единообразными. И ваши примеры и большинство примеров в интернете сводятся к тому чтобы получить что-то целове и готовое (файл, картинку, html-страницу). А если речь идет о данных по сложной выборке?
Сравните:
- Эй, сервер, дай данные по выборке. Вот тебе удобный читаемый JSON с кучей параметров.
- Эй, сервер, дай данные по выборке. Вот тебе строка вида: ?%12%13%14%15&%26%27%28%29%20%&26%2626%26%26%26
Есть GET для получения данных, есть POST для создания, PUT для обновления. Вы когда выборку делаете, часто post и put используете? И часто рест апи через браузер работает? Наверное зря есть некоторый стандарты для выборки и фильтров выборки. Если вы придете ко мне с выборкой через put, я вас палкой побью, и буду прав. Ну както так.
Просто я всякое видел в урлах и апях, и то что есть сейчас рест апи, по сути просто описали то, что есть и было со времен царя гороха. И добавили PUT, PATCH, UPDATE, DELETE. А по факту это типы над post и get. Которые используют имя параметра в заголовках. Вы либо шлете все в теле, либо в строке вызова. Как то так.
Диалога не получилось. В любом случае спасибо за ответ.
Ну тут не диалог. Это истины и многолетний опыт разных интеграций. Тут больше на уровне ощущений. И многие поытки обьяснить как это работает чисто теория, лучше практики только практика. И желательно качественная практика.
Еще вот хорошее замечание, если вы используете query параметры в гет, то можно добавить кеширование. А в теле запроса не сможете.
А по факту это типы над post и get. Которые используют имя параметра в заголовках.
Это очень грубо сказано:
PUT = POST + Флаг возможной идемпотентности + Рефреш кеша, где ключом кеша является URI
PATCH = POST + Рефреш кеша, где ключом кеша является URI
DELETE = POST + Сброс кеша, где ключом кеша является URI
По факту всего этого можно добится обычным POST с манипуляциями телом ответа, статус кодами и значениями заголовков.
И часто рест апи через браузер работает?
Вам не кажется странным, когда что-то, что ссылается на REST через HTTP, не работает в браузере? Имеет ли смысл ссылаться на REST в таком случае?
Как будто бы все, что начинает работать по REST, в конечном итоге становится браузером. Иначе в этом нет смысла.
У меня полно было кейсов интеграций рестов over хттп, которые не отсвечивали нигде. Потому что сусурити. И это прям сиситемные интеграции крупного бизнеса на кровавом интерпрайзе.
Просто это транспорт и способ общения. На мой взгляд его переоценили. Есть масса вариантов делать тоже самое. Просто рест и json немного удобнее, хотя там тоже есть маленькая тележка минусов. Ведь жили люди много лет на soap, и ничего. И сейчас живут и очень даже успешно
Нет даже не так: рест используют потому что с хттп транспортом меньше мороки. Тому как в хедеры напихал параметры и все, ты уже авторизован. К примеру тотже телнет, прикрути к нему ссх или ссл, так там и авторизация дважды... И еще все в одну строку, и ответ еще распарсить надо... А еще коннект открой, закрой, эти хендшейки если нужен постоянный конект... Я человек не прихотливый, для меня это все одинаково, различия в деталях. Но телнет быстрее и мне нравится больше... Безопаснее, на мой взгляд...
Я вам об этом же и говорю.
То, что называют REST API это не REST, пока там не используется HATEOAS. Для того, чтобы нормально работал HATEOAS нужен подготовленный клиент - браузер.
Описанное в статье это RPC c транспортом по HTTP. Передавай параметры как хочешь - в сегменте пути, в строке запроса, в заголовках, в теле запроса. И частично переиспользуй существующую инфраструктуру DNS, прокси, реверс прокси и тд.
В коммуникации machine-to-machine гипермедиа не работает. Не умеют машины понимать семантику заложенную в HTML форму; например, если разработчик решил изменить поле формы Full Name на First Name & Last Name - пользователь-человек поймет и адаптируется, в отличии от машины.
Поэтому машины общаются по RPC. Для разработчика интеграции нет никакой разницы между:
PATCH /customers/123/address
POST /update_customer_address/123
POST /customers/123:updateAddress
gRPC вызов
jsonRPC вызов
GraphQL вызов
SOAP вызов
Так что нет, я не согласен в том, что RESTful API это корректное определение для данного класса API. Web API - может быть. И да, я согласен, что было бы неплохо выработать какие-то стандарты, чтобы разработчик быстрее ориентироваться в семантике API и когда изучает документацию работал принцип наименьшего удивления.
Но без натягивания совы на глобус. Это слишком сбивает с толку, особенно начинающих инженеров. Я сам первые пару лет вообще не понимал, что происходит, почему я разрабатываю интеграции и сталкиваюсь с двумя координально разными стилями API, и "якобы" RESTful API всегда оказывается сложнее и выглядит более перегруженным, чем тот же RPC как в Stripe API или Slack API. И то же самое, когда я сам разрабатываю API: "правило" четко гласит, что в URI не должно быть глаголов, все должно быть выражено через "ресурс". Я, как ведомый несмышленыш, вместо вызова "POST /customers/123:sendEmail" исхитрялся с созданием какого-то ресурса "PUT /customers/123/emailDispatches или POST /emailDispatchtes и ID в теле запроса", чтобы на ревью архитекторы не завернули и не дай бог усомнились в моей компетентности.
А когда я наконец вдумчиво прочитал диссертацию Роя Филдинга, а так же дискуссии с его участием на его веб сайте - тогда стало понятно, что это просто абсолютно некорретно ассоциировать RPC API и RESTful API (на котором работает гипермедиа веб). Внезапно оказалось, что архитекторы сами не шарят и создают карго культ вокруг в корне неверных подходов, защищая свою элитарность флером сакральности знаний и опыта, но это другая тема :)
Очень не хочется вводить новое поколение в заблуждение, пусть они уже с большей части вайб-кодеры :)
Паттерны интеграции API