Обсуждение дизайна RESTful API: сложный запрос для спокойной конечной точки

Question

Я проектирую RESTful api для большой коллекции данных отчетности, я хотел бы передать сложный набор параметров, например, в кодовом блоке ниже. Я обсуждаю использование POST и GET для этой конечной точки. Член команды, похоже, выступает в пользу GET, но я не уверен, что лучший способ передать этот объем данных в качестве параметров GET. Лучшая идея заключается в том, чтобы иметь один параметр GET, называемый как-то вроде jsonparams, который будет иметь все ниже кодированное json

{ 
    "filters": 
    [ 
     { 
     "field": "metric-name", 
     "gt": (float/int), 
     "lt": (float/int) 
     }, 
     { 
     "field": "metric-name-2", 
     "gt": (float/int), 
     "lt": (float/int) 
     } 
    ], 
    "sort": 
    [ 
     { 
     "field": "metic-name", 
     "order": "ASC"/"DESC" 
     }, 
     { 
     "field": "metic-name-2", 
     "order": "ASC"/"DESC" 
     } 
    ] 
    "limit": 100, 
    "offset": 0 
} 

Answer 1

Если вы добавляете данные в ресурс или создаете ресурс, используйте POST. GET - получить уже существующий ресурс, а не изменять состояние ресурсов.

Если аргумент идти с сумасшедшим серийным запросом на основе параметра GET для какой-то простой простой процедуры, вы не будете прислушиваться к REST.

Теперь, если вы извлекаете ресурсы только (без создания), используйте GET. Хотя я предпочитаю персонализированные параметры, это не требуется. Если ваша ситуация 100% поиска вы можете кодировать весь набор в в гигантском кодируются пары строки, но я хотел бы предложить, по крайней мере, разделив его немного для улучшения вменяемости, делая что-то вроде:

/resource?filters=urlencoded_filter_array&sort=urlencoded_sort_array&offset=0&count=100 

или вы может пойти более явные, как:

/resource?filter1=urlencoded_filter_json&filter2=urlencoded_filter_json .... sort2=urlencoded_sort_json&offset=0&count=100 

или, наконец, (мой любимый) совершенно четко вырвались набор Params

/resource?filter1_field=bah&filter1_gt=1.0&filter1_lt<2&filter2_field=boo&filter2_lt... 

Мне нравится окончательная, потому что нет encodein g/декодирование json и затем url, кодирующий всю строку json. Этот формат легко расшифровывается в журналах доступа и проблемах. Это также очень кэшируемо, даже если порядок параметров изменен, некоторые кэши прокси-сервера все еще могут работать с этим, тогда как кодирование некоторых фильтров в объекте json, если они перемещаются вокруг, выглядят совсем другими значениями, насколько это касается прокси-серверов , Для меня это самый REST дружественный (если это имеет смысл), хотя первые 2 примера - это хорошие запросы REST GET.

Добавленная работа по анализу имени параметра на самом деле не такая уж большая проблема. Простой метод может преобразовать ваш json в строку параметров, а другой простой может повторно убрать json-объект из формата explict filter1_xyz.

Answer 2

POST - это метод, используемый для любой операции, которая не стандартизирована по протоколу HTTP. Поиск стандартизован методом GET, поэтому использование POST для получения информации, соответствующей потенциальному ресурсу, никогда не является RESTful. Теоретически, вы должны использовать GET, независимо от того, насколько изощрен ваш URI.

Однако, поскольку вы выполняете запрос, для которого нет одного ресурса, с которым вы могли бы выполнить GET, кажется, что использовать POST достаточно, если вы знаете об этих недостатках, и ваша документация ясно об этом. Честно говоря, я думаю, что использование POST намного яснее, чем кодирование этой полезной нагрузки как JSON + base64 и отправка ее в качестве запроса только для пуризма.

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

Если вы решили пойти с GET, есть улов.В то время как спецификации HTTP не устанавливают ограничений для URI, большинство реализаций, и вы можете попасть в этот предел, если вам нужно передать все эти параметры в качестве запроса. В этом случае RESTful обходит ограничения основной реализации, если это отделилось от вашего приложения. Соглашение о том, что вы хотите, будет использовать метод POST с полезной нагрузкой, описанной выше, и заголовок X-HTTP-Method-Override: GET.