Посоветуйте, пожалуйста, современных документов про дизайн гайды 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-ов на клиенте?
Как правильно задизайнить сохранение пачки записей? Это нужно, современно (вспомним как клихаус просит пихать по сотне тысяч записей), но как это совместить с валидацией?
Короче, пачка несвязанных вопросов, поэтому повторю вопрос: поделитесь пожалуйста ссылками на описанные современные дизайны, может получится что-то почерпнуть из бурлящих вопросов.
Comments