oka_volga Nov 11 2018 at 22:28

Правильный JSON API или JSON RPC

2 min

21K

API*Programming*

-24

Comments 23

robert_ayrapetyan Nov 11 2018 at 23:10

Непонятно зачем это нужно. Существующие стандарты JSON-RPC и так гибкие дальше некуда. Передавайте sign параметром, кто мешает. Переименовали param -> data, назвали это новым стандартом… Такое себе. Приведите хоть один реальный пример, где ваш «стандарт» окажется лучше существующего 2.0 и поясните в чем именно будет преимущество.

oka_volga Nov 12 2018 at 08:08

Передавайте sign параметром, кто мешает.

Мешает стандарт.
в стандарте предусмотрено 4 параметра:

{"jsonrpc": "2.0", "method": "subtract", "params": [42, 23], "id": 1}

и «sign» можно добавит только в «params», но в параметрах должны быть данные и помещать туда подпись можно но, мне кажется, не совсем логично.

Переименовали param -> data

Опять, же с точки зрения логики. мы передаем не просто параметры. а данные т.е. data и принимаем не просто результат, а данные т.е. data.

А понятие результат сводится к получению «флага» успех или ошибка и мы будем обрабатывать полученные данные в зависимости от «флага».

т.е. при стандартном подходе логика обработки ответа примерно такая:
вариант 1 success
1. получили ответ
2. есть ли параметр result
3. обрабатываем result

вариант 2 error
1. получили ответ
2. есть ли параметр result
3. если нет — ищем параметр error
4. если есть error — обрабатываем

При моем подходе. примерно так:
вариант 1 success
1. получили ответ
2. есть ли параметр result и он == success
3. обрабатываем data. если нужно

вариант 2 error
1. получили ответ
2. есть ли параметр result и он == error
3. обрабатываем data

Мне кажется, что мой вариант немного логичней, но это не точно)

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

Хотя мои сомнения появились когда я начал делать проект с использованием микро-сервисной архитектуры. А для обмена данными между сервисами есть 2 основных варианта
RPC или Message Bus. Я как раз остановился на RPC. Но может нужен другой стандарт?
Типа: Remote Service Call (Удаленный вызов сервиса)?

Тогда мое творчество можно назвать по другому, типа: JSON-RPS Version 1.0 )

mwizard Nov 12 2018 at 13:15

А зачем нужен sign? Если это для защиты целостности сообщений, то как бы почему не общепринятый TLS? Если же это для JWT-токена, то почему не общепринятый `Authorization: Bearer`?

oka_volga Nov 12 2018 at 13:32

А зачем нужен sign? Если это для защиты целостности сообщений, то как бы почему не общепринятый TLS? Если же это для JWT-токена, то почему не общепринятый `Authorization: Bearer`?

TLS не имеет отношения к RPC, это шифрование протокола, а мы наоборот от протокола передачи данных абстрагируемся.
JWT вещь отличная, но это это открытый стандарт (RFC 7519) для создания токенов доступа и к RPC тоже никак не относится.

Токен в конечном итоге это некая хешированная строка, как вы ее создадите, по каким стандартам не важно. А передавать то этот токен как то нужно. Для этого параметр «sign», для передачи токен строки или нескольких строк.

mwizard Nov 12 2018 at 13:35

Вы так и не ответили, зачем он нужен. Если этот sign не нужен, то и передавать его нет смысла. Тем более, вы «абстрагируетесь от протокола передачи данных», но тем не менее, навязываете какое-то дополнительное невнятное поле, задачи которого с головой покрываются транспортными средствами.

Или это все же про «подпись» md5(«super»+args+«secret») в духе flash-игр начала 2000-х?

oka_volga Nov 12 2018 at 15:58

md5(«super»+args+«secret») в духе flash-игр начала 2000-х?

Возможно) или можно
hash('sha256', $json),
или можно передать JWT token, это же просто строка

Пример готового JWT:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.EkN-DOsnsuRjRO6BxXemmJDm3HbxrbRzXglbN2S4sOkopdU4IsDxTI8jO19W_A4K8ZPJijNLis4EZsHeY559a4DFOd50_OqgHGuERTqYZyuhtF39yxJPAjUESwxk2J5k_4zM3O-vtd1Ghyo4IbqKKSy6J9mTniYJPenn5-HIirE

Но даже если это не строка, какая разница, передавайте все. что душе угодно в этом параметре, лишь бы вы были уверены, что это авторизированный запрос.

навязываете какое-то дополнительное невнятное поле

Поле не обязательное.

mwizard Nov 12 2018 at 16:01

Сорян, вы говорите глупости. Для «авторизированности» запроса токен передается в хедере Authorization, для чего он и был создан. Для проверки целостности запроса и идентификации отправителя используйте TLS, для чего он и был создан.

Вы же придумываете костыль поверх костыля, не понимая основных принципов работы того, что вы пытаетесь своим костылем заменить. Не делайте так.

oka_volga Nov 12 2018 at 17:53

Честно говоря не ожидал такой агрессии и непонимания(
Хотел уже было пуститься в аргументированный спор, но не вижу смысла.

Вы для себя все решили. Имеете право.

gdsmiler Nov 13 2018 at 09:11

Ну нет, давайте все таки Вашу аргументацию. Интересно все таки, чем вам не подходят существующие механизмы, указанные предыдущим комментатором

oka_volga Nov 13 2018 at 09:45

Всё устраивает)

Все

существующие механизмы

для чего то предназначены и используются по назначению.

Что бы завершить эти не конструктивные споры, нашел сегодня пару примеров,
как Yandex и Сбербанк используют токены в своих JSON API вы при желании можете найти еще множество примеров.
Дополнил этими примерами свою статью, смотрите после «PS:»

Повторюсь:

Важно понимать, что токены и подписи в API используются часто, естественно на ряду с другими методами защиты. И те кто работает с разного рода API, прекрасно это знают.

oka_volga Nov 12 2018 at 13:21

Тогда мое творчество можно назвать по другому, типа: JSON-RPS Version 1.0 )

имел в виду JSON-RSC (Remote Service Call)

mwizard Nov 11 2018 at 23:28

Спасибо, это не нужно, закапывайте.

SDKiller Nov 12 2018 at 01:57

Алилуйя, вы изобрели велосипед.

SDKiller Nov 12 2018 at 01:57

jsonapi.org

r1000ru Nov 12 2018 at 06:00

Тут есть два момента — RPC (remote procedure call), оно же удаленный вызов процедуры. С каких-то древнейших времен повелось, что у процедуры могут быть «параметры» и она возвращает «результат».

В вашей реализации, где в result вы передаете success или ошибку, я не могу результат мапить на конструктор объекта, его использующий. А в jsonrpc 2.0 — могу смело. Наличие result — гарантирует что результат получен. Наличие error — гарантирует что произошла ошибка. Одновременно их быть не может. К тому же наличие error.code позволит мне сделать локализацию, а добавление error.data — позволит подробно описать условия выполнения ошибки, для дальнейшей отладки. В зависимости от логики обработки, мне ничто не мешает передавать session_id (к примеру) как параметр или какой-нибудь X-Auth-Token в заголовке.

oka_volga Nov 12 2018 at 06:55

С каких-то древнейших времен повелось, что у процедуры могут быть «параметры» и она возвращает «результат».

Открыли мне глаза, практически. Видимо я не такой старый)
Но для меня результат и получаемые данные, это не одно и тоже.
т.к. результат на запрос мы получаем всегда, даже когда сервер молчит, это все равно результат.

result вы передаете success или ошибку, я не могу результат мапить

в этом и смысл. Хотите мапить result, а его там нет, там error. Естественно, это все проверяется. Но мне показалось логичным, в начале понять, что нужно сделать, т.е.

result = success — обрабатываем данные из data
result = error — реагируем на ошибку, а все данные о ошибке в data

просто отделил сообщение о результате от данных, мне пока кажется это логичным.

мне ничто не мешает передавать session_id (к примеру) как параметр или какой-нибудь X-Auth-Token в заголовке.

да, согласен. но если «общаются» 2 сервера и нужно абстрагироваться от канала?
т.е. мы не знаем, что за канал передачи данных и о заголовках тоже ничего не знаем. А идентифицировать запросы, а в ряде случаев и ответы нужно.

r1000ru Nov 12 2018 at 07:31

Ответ, ошибка и отсутствие ответа — это результат запроса. А поле result по спецификации jsonrpc 2.0 — это результат выполнения вызываемой процедуры. Если процедуру выполнить успешно не удалось — результата нет и есть ошибка. Впрочем ваш вариант тоже имеет право на жизнь, но я от такой схемы отказался, мне проще проверить наличие свойства error, а не его значение. И при его отсутствии — вызвать обработчик результата. В противном случае — обработчик ошибки.

JsonRPC 2.0 позволяет идентифицировать запросы и ответы по идентификатору. Ничто не мешает передавать идентификатор сессии в params — так будет работать везде, хоть через HTTP, хоть через брокеры сообщений/запросов (я использую NATS — очень надежный механизм, рекомендую).

oka_volga Nov 12 2018 at 08:35

Согласен,

Ничто не мешает передавать идентификатор сессии в params

писал, по этому поводу чуть выше:

«sign» можно добавит только в «params», но в параметрах должны быть данные и помещать туда подпись можно но, мне кажется, не совсем логично.

Думаю лучше провести идентификацию немного раньше, не разбирая данные, данных может быть очень много, зачем нам тратить ресурсы на их разбор, если это не авторизированный запрос?

oka_volga Nov 12 2018 at 08:36

Впрочем ваш вариант тоже имеет право на жизнь,

Спасибо! И я считаю, что на вкус и цвет…

r1000ru Nov 12 2018 at 09:17

А вот в этом заключается очень частый просчет разработчиков различных API. Часто делают так (простой пример обновления профиля пользователя):

{ 
   "session_id": "fc94bb40-b938-409e-9855-3dc283680a0a",
   "password": "verysecretpassword",
   "first_name": "Vasia",
  "last_name": "pupkin",
  "birth_day": "2000-01-01"
}

Что и приводит к необходимости очищать данные от сессии и пароля, после их проверки.

Если запрос построить так:

{ 
   "session_id": "fc94bb40-b938-409e-9855-3dc283680a0a",
   "password": "verysecretpassword",
   "person": {
       "first_name": "Vasia",
       "last_name": "pupkin",
       "birth_day": "2000-01-01"
    }
}

то на каждый шаг требуется только одно свойство:

Проверяем валидность сессии по session_id (и получаем идентификатор пользователя)
Проверяем пароль по password и идентификатору профиля
Вызываем обновление данных профиля по содержимому profile
В любой момент мы можем прекратить действия.

oka_volga Nov 12 2018 at 09:51

Думаю лучше провести идентификацию немного раньше, не разбирая данные, данных может быть очень много, зачем нам тратить ресурсы на их разбор, если это не авторизированный запрос?

Нет, это не аргумент, отвечаю сам себе)))
т.к. не важно где находится параметр «sign», к моменту его поиска в запросе, JSON уже должен быть разобран(

dmitry_dvm Nov 12 2018 at 07:25

Для себя раз и навсегда решил сделать так: всегда приходят data, issuccess и errors. Issuccess зависит тупо от содержимого errors (issuccess => errors==null). В errors есть code, message и description. Сам ответ всегда одинаковой структуры и его спокойно можно десериализовать в объект на клиенте с любой типизацией. Ориентировался на дотнет. Все это дарует неисчислимые блага на клиенте и унификацию апи, все счастливы. И никакого гемора с разбором ответов, когда то есть данные, то их нет.

oka_volga Nov 12 2018 at 08:12

Я так понял, что вы предпочитаете подход похожий на мой