Думы о web-API. часть первая

[napa3um]

Вы не поняли сути различия REST и RPC. Это равномощные концепции, выразимые друг через друга, но смешивать их вредно. В терминах REST выполнение процедуры из RPC будет созданием нового одиночного ресурса «операция». REST придуман для того, чтобы явно выражать _состояние_ персистентных моделей на клиенте и сервере и безконфликтной синхронизации между ними. REST — это набор ограничений (на виды ресурсов и операции с ними) над RPC, способ упорядочивания «произвольных операций», чтобы они с меньшей вероятностью противоречили друг другу и не приводили к неконсистентным состояниям моделей. RPC — это уличная драка клиента с сервером, REST — этот поединок в стиле джиуджитсу.

[napa3um]

Ваш пример о включении одного ресурса в другой (пользователя в группу модераторов, например) в концепции REST будет созданием ресурса «членствоПользователяВГруппе», без необходимости придумывать для этого отдельную семантику операции над RPC (например, не придётся заботиться об идемпотентности этой операции или о видах ошибок при её выполнении).

[marapper]

REST — это набор ограничений (на виды ресурсов и операции с ними) над RPC

Странное смешение.
RPC — глаголы-методы-ресурсы, единая точка входа, автодискаверинг методов по ней, обычно точно описанный протокол типа SOAP, xml-rpc, json-rpc
REST — архитектура гипертекстовых операций, CRUD, урлы-ресурсы и глаголы в методах. Все остальное, точки входа, дискаверинг, документация — на совести реализаций, типа HATEOAS, JSON API, oData.

[napa3um]

Вы смешали архитектурный стиль с конкретными реализациями. В архитектурном смысле RPC (Remote Procedure Call) — вызов _произвольных_ методов, REST (REpresentational State Transfer) — вызов _ограниченного_ набора методов изменения состояния ресурсов. (HATEOAS/HAL в REST/HTTP и WSDL в RPC/SOAP — отдельная тема, которой я не касался в своём комментарии.)

[Accetone]

Почему не подойдет следующее:

Для авторизации:
POST /api/v1/sessions


Для вступления пользователя в группу:
POST /api/v1/groups/42/members

POST /api/v1/groups/42/moderators


[marapper]

Семантичнее и в стиле CRUD

POST /api/v1/member/42/groups
{groups: [1, 2, 3]}

[Defff]

Как-то достаточно сложная архитектура у Автора
Зачастую удобнее использовать идентификатор пользователя(автора) в каждом из создаваемых ключей(в качестве его части), а в АPI иметь поисковый сборщик по ключам( значение поиска по имени ключа задаём в запросе нужной регуляркой), сборщик отдаёт на клиента все найденные ключи вместе с их значениями, тем самым мы можем избежать конфликтов одновременной попытки изменения-модификации объекта данного ключа разными пользователями, так как каждый ключ пишется только одним юзером. Исчезают проблемы конфликтов одновременного доступа на запись-модификацию.

[marapper]

> Скалярные значения

PATCH и частичный апдейт объекта.

[kleinmaximus]

GraphQL нам в помощь :)