Здравствуйте, Sinclair, Вы писали:

C>>Да, это плохо. Все ограничения и способности API должны быть описаны в его схеме. По факту в REST это совсем не так.
S>По факту это никогда не так. Схема описывает только маленький кусочек поведения API. Тут по соседству обсуждали вопросы тестирования — я там иллюстрацию приводил.
Схема может описывать достаточно большой кусок API. По крайней мере, она однозначно может описывать все аргументы метода. В REST на практике нет даже этого.

C>>Например, имеем вот это API: https://docs.docker.com/engine/api/v1.41/#operation/ContainerArchiveInfo — "взять архив файловой системы".
S>Нет, "взять архив файловой системы" — это https://docs.docker.com/engine/api/v1.41/#operation/ContainerArchive. А то, что вы показали — это "взять информацию об архиве файловой системы".
Ага. Но это скорее вопрос к уродам, которые делают документацию в виде бесконечной страницы, которая меняет адресную строку при прокрутке.

C>>Внимание, вопрос! Как это API будет взаимодействовать с Range?
S>Тот, который вы указали — никак. Запрос HEAD не поддерживает хидер Range
S>Зато вызвав HEAD, мы получим (или не получим) заголовок Accept-Ranges, который скажет всё, что нам надо знать.
Т.е. надо иметь копию сервера, причём работающую. И создать ситуацию, когда этот метод можно вызвать.

S>А можем просто сразу сделать GET запрос с Range.
S>Если сервер не умеет в Range, то он просто вернёт полный файл.
S>При этом мы никогда не перепутаем частичный респонс с полным — поэтому у нас корректно работают любые комбинации клиента и сервера.
И как мы это счастье будем тестировать? Код с использованием Range в интеграционных тестах не будет использоваться. Писать сразу нетленку без багов и надеяться, что если Docker в какой-то момент таки добавит Range, то всё будет работать сразу правильно?

Никакие из известных мне генераторов кода по OpenAPI автоматически Range не поддерживают, кстати. Так что надеяться на инструментарий тоже не получится.

C>>Не видел пока вообще ни одного API, где был бы conditional get. Более того, я даже не видел клиентов, которые его бы поддерживали.
S>Любой браузер и любой прокси-сервер.
Браузер тоже не поддерживает для всего. XMLHttpRequest его автоматически не умеет. Так что автоматически он будет только для ресурсов, которые включаются в HTML (т.е. изображения, скрипты, CSS).

Это такое мизерное достоинство, что несерьёзно.

C>>Так что на практике получается, что всё преимущество REST API заключается ровно в одном сценарии с выдачей статических файлов, и может быть реализована только при использовании клиента, который специально написан для этого.
S>Отчего же "статических"?
Из-за того, что для нестатических conditional get бессмыслен. Т.е. файл не должен меняться, по крайней мере часто.

S>Пример такого gRPC API в живой природе можно увидеть?
Это практически пример из моего API в приложении, только у меня он в обратную сторону (upload).

Но если хочется публичного API, то вот: https://github.com/googleapis/googleapis/blob/master/google/storage/v2/storage.proto#L623

C>>По API сразу понятно что и как использовать. Не надо гадать: "А поддерживает ли API-сервер Range?"
S>При желании, так можно сделать и в REST. Например, многие протоколы вместо Range:items поддерживают явные параметры size и page.
Можно. Но тогда нет никаких преимуществ перед gRPC.