Посоветуйте, пожалуйста, современных документов про дизайн гайды API



Коллеги, посоветуйте пожалуйста современных документов про дизайн гайды API. Т.е. задача такая: я думаю, что у меня получится сделать единый дизайн всех API моей компании с едиными правилами нейминга, организации запросов и ожидаемых ответов.
С чем у меня возникли вопросы: вроде как длительное время стандартный ответ на то, как делать API (если это не SOAP или не gRPC) был REST. При этом на какие-то вопросы REST не отвечает, а на другие отвечает весьма странно, так что он не является тем, на что можно положиться и просто сказать: у нас rest api.
Приведу несколько примеров.
Во-первых, вопрос пагинации по коллекциям. Со времен рельс у меня была простая картина: page + limit. Сегодня такой подход кажется неразумным, потому как:
* на быстро дописывающейся коллекции запрос с одним и тем же page уже дает разные данные, а изменение этого page фактически хаотично бессистемно скачет по выборке
* большой page — готовый самодельный DOS для своего сервиса
Переходим от page + limit к where + sort, получаем необходимость дописывать на сервере в поля сортировки тот же id, чтобы получить стабильную сортировку. Приходим к концепции курсоров, которые нужны для того, чтобы клиент не забывал дописывать искусственно добавленные поля.
Дальше пример со сложными запросами. Начинаем усложнять, придумывать третий синтаксис поверх query string и приходим к тому, что пора брать монговский синтаксис для запросов, а он начинает не влезать в base64 виде в query string. Получается, что разумнее сделать POST запрос с обычным жсоном в поле. Диковато звучит, но я уже смирился с этим.
Ещё пример с идемпотентностью апи. Рест строго против этого, а это жутко удобная штука и чрезвычайно нужная в современном мире.
Можно ли позволять рельсовикам дальше делать свои автоинкрементные айдишники (удобные ведь) или уже всё, отказаться от них
в пользу uuid-ов на клиенте?
Как правильно задизайнить сохранение пачки записей? Это нужно, современно (вспомним как клихаус просит пихать по сотне тысяч записей), но как это совместить с валидацией?
Короче, пачка несвязанных вопросов, поэтому повторю вопрос: поделитесь пожалуйста ссылками на описанные современные дизайны, может получится что-то почерпнуть из бурлящих вопросов.
97   35  
  1. Alexey Rybak 15 дней назад
    К паджинации gid
    • Макс Лапшин 15 дней назад
      gid — это кто?
    • Alexey Rybak 15 дней назад
      Макс Лапшин generation id
    • Макс Лапшин 15 дней назад
      не видел такой термин, посмотрю, спасибо
    • Денис Габайдулин 15 дней назад
      Alexey Rybak это может быть просто снапшотинг результатов выдачи также. В поиске огромная проблема длинный результат выдачи с пагинацией. В кратце, если у тебя условно матрёшка из сервисов, которые по разному ранжируют результат выдачи, то протащить там корректный total довольно сложно из-за коллапсинга.
    • Макс Лапшин 15 дней назад
      ага
  2. Денис Габайдулин 15 дней назад
    Я не сильно эксперт в API, но почему нельзя делать идемпотентные вызовы через PUT/DELETE?
    • Макс Лапшин 15 дней назад
      смотри, сделать можно совершенно всё, вопрос в логичном наборе неконфликтующих договоренностей, которые не выглядят каким-то чуждым современной практике костылем.
    • Макс Лапшин 15 дней назад
      Денис Габайдулин ага, skuid кажется оттуда же
    • Юрий Баландин 15 дней назад
      Макс Лапшин (Max Lapshin) > 1) POST остается для GET с очень длинным запросом, потому что у GET сильно ограничены данные на вход
  3. Владимир Степанов 15 дней назад
    ?
    • Макс Лапшин 15 дней назад
      погляжу
    • Владимир Степанов 15 дней назад
      вот тут ещё по-моему были хорошие ссылки https://medium.com/.../openapi-and-grpc-side-by-side...
  4. Филипп Дельгядо 15 дней назад
    Ну, REST level 2 для реального использования вообще не очень пригоден, REST level 1 получше.Идемпотентность можно реализовать через два запроса: nextId и create. Autoincrement только для первого, понятное дело. Пагинацию сейчас вообще особого смысла использовать нет для сколь-нибудь нагруженных проектов. Небольшие коллекции с бэка проще забирать целиком, для больших чаще нужен infinite scroll, там достаточно передавать from и единственный вариант сортировки.
    • Игорь Беспальчук 15 дней назад
      Филипп Дельгядо А каким конкретно способом ты рекомендуешь делать infinite scroll?
    • Филипп Дельгядо 15 дней назад
      Обычно "много данных" - это какая-то история операций или что-то вроде, с естественной сортировкой. Там достаточно иметь порядковый номер (или дату) и запрашивать "N записей, сделанных раньше такой-то". Дофильтровывать, если надо, можно и прямо на клиенте. А какие еще могут быть варианты?
    • Олексій Вайсруб 15 дней назад
      Игорь Беспальчук Да, именно так. Если это интернет-магазин со списком товаров или список студентов в группе - то это не критично, а когда что-то реалтаймово-активно-меняющееся, то пажинация становится головняковой.
  5. Игорь Лидин 15 дней назад
    Во-первых, gRPC. Во-вторых, пейджинг хорошо работает по снапшотам. А как делать снапшот данных — от использования MVCC в БД до where created <= date.
    • Филипп Дельгядо 15 дней назад
      Игорь Лидин, а что хорошего в gRPC? И формат фиговенький и с десериализацией все грустно и редакторы так себе. Т.е. тот же json обычно гораздо удобнее. Особенно в формате "нормальный язык -> OpenApi -> генерация клиентов для всех прочих"
    • Филипп Дельгядо 15 дней назад
      Константин Токар, да пофиг же, генераторы никуда не денутся. Ну и с gRPC не лучше, его гугл для себя меняет как хочет
  6. Андрей Литвиненко 15 дней назад
    Серебряной пули нет. Делайте как нужно вашему сервису/продукту/компании. Универсальные решения плохи. Если хотите единый дизайн всех апи, соберите лидов и договоритесь сделать так чтобы всем было удобно или как минимум понятно.Ну
  7. Олексій Вайсруб 15 дней назад
    Ну как бы у нас сложилось что если говорим REST - то формат должен влазить и соответствовать Swagger/OpenAPI.
    • Макс Лапшин 15 дней назад
      если честно, то догматический REST очень не хочется.
    • Олексій Вайсруб 15 дней назад
      Макс Лапшин Амазон RDS очень даже живой и существует. Впрочем как и Аврора и Редшифт. И RedHat вроде тоже "классические" реляционные базы из дистрибутива ещё не выбросил.
    • Филипп Дельгядо 15 дней назад
      В Swagger можно описать почти что угодно. Rest level 1 точно без проблем, а там ничего кроме POST вообще нет (и это прекрасно)
  8. Andrey Pechorin 15 дней назад
    В итоге после мучений с попытками описать через protobuf запросы (а не только данные) пришли к openapi (и желательно >= 3.0). И вот щас отлично живем. Офигенно. Главное валидировать входные и выходные данные по этому контракту, а не только сам контракт валидировать и тогда это смысл имеет. Но компрессия - другой вопрос.
    • Andrey Pechorin 15 дней назад
      Никогда так спокойно себя не ощущал как с появлением openapi в моей жизни
    • Олексій Вайсруб 15 дней назад
      Andrey Pechorin Его же обычно не сразу "хочется", а когда проект уже как-то работает
    • Филипп Дельгядо 15 дней назад
      А как авторизация мешает OpenApi? Все в заголовках же?
    • Andrey Pechorin 15 дней назад
      Ко мне недавно приходили с вопросом про графql, ну и были как бы отправлены в сторону ребят которым нравится такими решениями заниматься. Мы не про это.
  9. Александр Павлов 15 дней назад
    1. Генерация id клиенте очень удобно (mongo из примера с его ObjectId генерацией на клиенте).2. query string из-за отсутствия типизации приведет к PUT вероятно (разве json пихать в qs) в content-type: application/json.3. Почему REST не идемпотентный не понял из поста, семантика http методов в REST предполагает идемпотентность для ряда методов: GET/HEAD/PUT4. Валидаторы на схемы запроса/ответа кажется разумно иметь декларативными и собираемыми из кусов (yml merge/link), для описания сущностей и композиции. Тут можно в сторону JsonSchema/OpenAPI посмотреть или чего угодно похожего по смыслу. (https://github.com/ajv-validator/ajv). По ним же строить документацию автоматизировано.5. REST действительно странно ложится или натягивается на какие-то моменты. Например в отношении связей сущностей, может трактоваться такое не однозначно при чтении документации.6. Удобно иметь карту преобразований Model -> Dto, Dto -> Model по 1 схеме декларативной желательно, по аналогии как в пункте 4, чтобы пока нет GraphQL клепать разные представления на 1 сущность. (Гидраторы, кажется, верно называется это)
    • Филипп Дельгядо 15 дней назад
      Я, кстати, больше люблю модель описывать на каком-нибудь приличном языке, а уже по нему строить OpenAPIIDE лучший редактор, да и рефакторить удобнее.
  10. Олег Вельмисов 15 дней назад
    Я вообще не понял из объяснения автора (какие-то странные доводы про DOS и как вообще один и то же постраничный запрос выдает разные результаты AKA не идемпотентный =)) почему не заходит постраничная навигация через дефолтный page? Мб Вы не умеете её готовить? В реляционной модели вообще никогда таких вопросов не возникало в NoSQL я хз. Best practise по дизайну реста ? Не не не слышал, лучше буду изобретать велосипед и заеду на хайпе через GraphQL или HETOAS
    • Макс Лапшин 15 дней назад
      не понял значит не дорос ещё
    • Гоша Юджиф 15 дней назад
      Макс Лапшин Я вот тоже не понял - перерос уже

Добавить ответ:
Отменить.