Як створити RESTful пошук / фільтрацію? [зачинено]

Наразі розробляю та впроваджую API RESTful у PHP. Однак я невдало реалізував свій початковий проект.

GET /users # list of users
GET /user/1 # get user with id 1
POST /user # create new user
PUT /user/1 # modify user with id 1
DELETE /user/1 # delete user with id 1

Поки що досить стандартний, правда?

Моя проблема - з першою GET /users. Я розглядав можливість надсилання параметрів в тіло запиту для фільтрації списку. Це тому, що я хочу мати можливість задавати складні фільтри, не отримуючи надто довгий URL, наприклад:

GET /users?parameter1=value1&parameter2=value2&parameter3=value3&parameter4=value4

Натомість я хотів мати щось на кшталт:

GET /users
# Request body:
{
    "parameter1": "value1",
    "parameter2": "value2",
    "parameter3": "value3",
    "parameter4": "value4"
}

що набагато читає і дає великі можливості для встановлення складних фільтрів.

У будь-якому разі file_get_contents('php://input')не повертав орган запиту про GETзапити. Я також спробував http_get_request_body(), але спільного хостингу, який я використовую, немає pecl_http. Не впевнений, що це все одно допомогло б.

Я знайшов це питання і зрозумів, що GET, ймовірно, не повинен мати орган запиту. Це було трохи непереконливо, але вони радили проти цього.

Тож зараз я не впевнений, що робити. Як ви спроектуєте функцію пошуку / фільтрування RESTful?

Я думаю, що я міг би скористатися POST, але це не здається дуже ВИПАДНИМ.

Найкращий спосіб здійснити пошук RESTful - це вважати сам пошук ресурсом. Тоді ви можете використовувати дієслово POST, оскільки ви створюєте пошук. Вам не потрібно буквально щось створювати в базі даних, щоб використовувати POST.

Наприклад:

Accept: application/json
Content-Type: application/json
POST http://example.com/people/searches
{
  "terms": {
    "ssn": "123456789"
  },
  "order": { ... },
  ...
}

Ви створюєте пошук з точки зору користувача. Деталі реалізації цього питання не мають значення. Деяким API RESTful може навіть не потрібна наполегливість. Це деталь реалізації.

Якщо ви використовуєте тіло запиту в GET-запиті, ви порушуєте принцип REST, оскільки ваш GET-запит не зможе кешуватися, оскільки система кешу використовує лише URL-адресу.

І що ще гірше, вашу URL-адресу не можна встановити в закладки, оскільки URL-адреса не містить усієї інформації, необхідної для перенаправлення користувача на цю сторінку

Використовуйте параметри URL або запиту замість параметрів тіла запиту.

наприклад:

/myapp?var1=xxxx&var2=xxxx
/myapp;var1=xxxx/resource;var2=xxxx 

Фактично, HTTP RFC 7231 говорить, що:

Корисне навантаження в повідомленні запиту GET не має визначеної семантики; надсилання тіла корисного навантаження на запит GET може призвести до відхилення запиту в деяких існуючих реалізаціях.

Для отримання додаткової інформації подивіться тут

Здається, що фільтрація / пошук ресурсів може бути реалізована RESTful способом. Ідея полягає у запровадженні нової кінцевої точки під назвою /filters/або /api/filters/.

Використання цього фільтра кінцевих точок може розглядатися як ресурс і, отже, створюватися POSTметодом. Таким чином, звичайно, тіло можна використовувати для перенесення всіх параметрів, а також можна створити складні структури пошуку / фільтрування.

Після створення такого фільтра є дві можливості отримати результат пошуку / фільтра.

1. Новий ресурс з унікальним ідентифікатором буде повернутий разом з 201 Createdкодом статусу. Тоді за допомогою цього ідентифікатора GETзапит може бути /api/users/таким:

   GET /api/users/?filterId=1234-abcd
   

2. Після створення нового фільтра через POSTнього він не відповість, 201 Createdа відразу 303 SeeOtherразом із Locationзаголовком, що вказує на /api/users/?filterId=1234-abcd. Це переспрямування буде автоматично оброблятися через базову бібліотеку.

В обох сценаріях потрібно зробити два запити, щоб отримати відфільтровані результати - це може розглядатися як недолік, особливо для мобільних додатків. Для мобільних додатків я б використовував один POSTдзвінок /api/users/filter/.

Як зберегти створені фільтри?

Вони можуть зберігатися в БД і використовуватись згодом. Вони також можуть зберігатися у деякому тимчасовому сховищі, наприклад, повторно та мати деякий TTL, після чого вони закінчуються та будуть вилучені.

Які переваги цієї ідеї?

Фільтри, відфільтровані результати є кешованими і можуть бути навіть закладені в закладки.

Я думаю, що вам слід скористатися параметрами запиту, але лише до тих пір, поки не буде відповідного заголовка HTTP для виконання того, що ви хочете зробити. Специфікація HTTP прямо не говорить про те, що GET не може мати тіло. Однак у цьому документі зазначено:

За умовою, коли використовується метод GET, вся інформація, необхідна для ідентифікації ресурсу, кодується в URI. У HTTP / 1.1 немає умов щодо безпечної взаємодії (наприклад, пошук), коли клієнт постачає дані серверу в тіло об'єкта HTTP, а не в частину запитів URI. Це означає, що для безпечних операцій URI можуть бути довгими.

Оскільки я використовую запуск laravel / php, я схиляюся до подібного:

/resource?filters[status_id]=1&filters[city]=Sydney&page=2&include=relatedResource

PHP автоматично перетворює []парами в масив, тому в цьому прикладі я закінчую a$filter змінною, яка містить масив / об'єкт фільтрів, разом зі сторінкою та будь-якими пов'язаними ресурсами, які я хочу з нетерпінням завантажувати.

Якщо ви використовуєте іншу мову, це все-таки може бути хорошою умовою, і ви можете створити аналізатор для перетворення []в масив.

Не бідайте занадто сильно, якщо ваш початковий API повністю ВІДКРИТИЙ чи ні (особливо, коли ви просто на стадії альфа). Почніть спочатку сантехніку працювати. Ви завжди можете зробити якесь перетворення / повторне написання URL-адрес, щоб відобразити зображення, ітеративно вдосконалюючись, поки не отримаєте щось досить стабільне для широкого тестування ("бета").

Ви можете визначити URI, параметри яких кодуються позицією та умовою на самих URI, з префіксом шляху, який ви знаєте, що ви завжди будете щось наводити на карту. Я не знаю PHP, але я б припустив, що такий інструмент існує (як він існує іншими мовами з веб-рамками):

.ie. Зробіть тип пошуку "користувачем" з парам [i] = значення [i] для i = 1..4 в магазині №1 (зі значенням1, значення2, значення3, ... як скорочення для параметрів запиту URI):

1) GET /store1/search/user/value1,value2,value3,value4

або

2) GET /store1/search/user,value1,value2,value3,value4

або як слід (хоча я б не рекомендував це, докладніше про це пізніше)

3) GET /search/store1,user,value1,value2,value3,value4

У варіанті 1 ви відображаєте всі URI з префіксом /store1/search/userдо обробника пошуку (або залежно від позначення PHP), дефолт виконує пошук ресурсів під store1 (еквівалентно /search?location=store1&type=user.

За умовами, задокументованими та застосованими API, значення параметрів від 1 до 4 відокремлюються комами та подаються в тому порядку.

Варіант 2 додає тип пошуку (в даному випадку user) як позиційний параметр №1. Будь-який варіант - це просто косметичний вибір.

Варіант 3 також можливий, але я не думаю, що мені це сподобалося б. Я думаю, що можливість пошуку в межах певних ресурсів повинна бути представлена ​​в самому URI перед самим пошуком (як би чітко вказуючи в URI, що пошук є специфічним у ресурсі).

Перевага цього над передаванням параметрів на URI полягає в тому, що пошук є частиною URI (таким чином трактуючи пошук як ресурс, ресурс, вміст якого може - і буде - змінюватися з часом.) Недоліком є ​​те, що порядок параметрів є обов'язковим .

Після того, як ви зробите щось подібне, ви можете використовувати GET, і це буде лише ресурс для читання (оскільки ви не можете POST або PUT на нього - він оновлюється, коли він GET'ed). Це також був би ресурс, який існує лише тоді, коли його викликають.

Можна також додати до нього більше семантики, кешуючи результати протягом певного періоду часу або за допомогою DELETE, що призведе до видалення кешу. Це, однак, може суперечити тому, що люди зазвичай використовують DELETE (і тому, що люди зазвичай керують кешуванням із заголовками кешування.)

Як ти будеш говорити про це, було б дизайнерським рішенням, але це був би шлях, яким я б ішов. Це не ідеально, і я впевнений, що будуть випадки, коли робити це не найкраще (особливо для дуже складних критеріїв пошуку).

FYI: Я знаю, що це трохи пізно, але для тих, хто зацікавлений. Залежить від того, наскільки ви хочете бути RESTful, вам доведеться реалізувати власні стратегії фільтрації, оскільки специфікація HTTP не дуже зрозуміла в цьому. Я хотів би запропонувати URL-кодування всіх параметрів фільтра, наприклад

GET api/users?filter=param1%3Dvalue1%26param2%3Dvalue2

Я знаю, що це некрасиво, але я думаю, що це самий НАЙКРАЩИЙ спосіб зробити це, і він повинен легко розібратися на стороні сервера :)