Мені трохи сумно бачити, що після більш ніж 10 років відповіді насправді не зазначено, як таке, що вимагається в ОП, може бути розроблено в архітектурі REST, отже, я відчуваю необхідність зробити це зараз.
Перш за все, що таке REST ?! Скорочення REST або ReST означає "Передача представницького стану" та визначає обмін станом ресурсу у певному форматі представлення. Формат представлення відповідає типу узгоджених засобів масової інформації. У випадку application/htmlформату представлення може бути потік текстового вмісту, відформатованого HTML, який відображається у браузері, ймовірно, після застосування певного форматування таблиці стилів для розміщення певних елементів у певних місцях.
REST - це, в принципі, узагальнення веб-переглядачів, про які ми всі знаємо, хоча націлені на всі види програм та не лише браузери. Тому, задумуючи, ті самі поняття, які застосовуються до Інтернету, застосовуються і до архітектури REST. Таке питання, як досягти чогось "RESTful" способом, вирішується навколо відповіді на питання, як чогось досягти на веб-сторінці, а потім застосувати ті самі поняття до рівня додатків.
Веб-калькулятор зазвичай може починатися з якоїсь "сторінки", яка дозволяє вводити деякі значення для обчислення, перш ніж надсилати введені дані на сервер. У HTML це зазвичай досягається за допомогою <form>елементів HTML, які навчають клієнта встановити доступні параметри, цільове місце для відправки запиту, а також формат представлення, який слід застосувати після надсилання вхідних даних. Це може виглядати приблизно так:
<html>
<head>
...
</head>
<body>
<form action="/../someResource" method="post" enctype="application/x-www-form-urlencoded">
<label for="firstNumber">First number:</label>
<input type="number" id="firstNumber" name="firstNumber"/>
<label for="secondNumber">Second number:</label>
<input type="number" id="secondNumber" name="secondNumber"/>
<input type="submit" value="Add numbers"/>
</form>
</body>
</html>
Наведений вище зразок, тобто стверджує, що є два поля введення, які можна заповнити або користувачем, або іншими автоматами, і що після виклику вхідного елемента введення браузер дбає про форматування вхідних даних у application/x-www-form-urlencodedформат подання, який надсилається до вказаного цільового місця через вказаний метод запиту HTTP, POSTу цьому випадку. Якщо ми введемо 1у firstNumberполе введення та 2у secondNumberполе введення, браузер сформує представлення firstNumber=1&secondNumber=2та надішле це як корисне навантаження фактичного запиту на цільовий ресурс.
Отже, необроблений запит HTTP, виданий серверу, може виглядати так:
POST /../someResource
Host: www.acme.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 28
Accept: application/html
firstNumber=1&secondNumber=2
Сервер може виконати обчислення та відповісти на подальшій HTML-сторінці, яка містить результат обчислення, оскільки в запиті було вказано, що клієнт розуміє цей формат.
Як вже зазначав Бретон, немає такого поняття, як "RESTful" URL або URI. URI / URL - це щось подібне, і воно не повинно передати жодному значенню клієнту / користувачеві. У зразку калькулятора вище користувача просто не цікавить, куди надсилати дані, просто цікавить те, що при запуску поля введення введення запит надсилається. Вся необхідна інформація, необхідна для виконання завдання, повинна бути надана сервером.
Також веб-переглядач може не знати про те, що запит насправді подає калькулятор з деякими вхідними параметрами, а також може бути якась форма замовлення, яка повертає лише наступне подання форми для продовження процесу замовлення або якийсь зовсім інший вид ресурс. Він просто виконує те, що вимагає специфікація HTML в такому випадку, і не може менше турбуватися, що насправді робить сервер. Ця концепція дозволяє веб-переглядачу використовувати той самий формат представлення, щоб робити всілякі речі, такі як замовлення деяких речей з улюбленого інтернет-магазину, спілкування в чаті з кращими друзями, вхід в онлайн-акаунт тощо.
Affordance деяких елементів, наприклад в разі введення уявити поле, яке зазвичай перекладається як кнопка, визначає те , що ви повинні , щоб з ним. Що стосується кнопки чи посилання, то вона, як правило, говорить вам про її натискання. Інші елементи можуть містити різні переваги. Така приналежність може бути виражена також через зв'язки , наприклад, з preloadанотованими посиланнями, які в основному говорять клієнту, що він вже може завантажувати вміст пов'язаного ресурсу у фоновому режимі, оскільки користувач, швидше за все, захопить цей контент далі. Такі відносини зв’язків, звичайно, повинні бути стандартизовані або слідувати механізму розширення для типів відносин, визначених веб- зв'язком .
Це основна концепція, яка використовується в Інтернеті і яка також повинна використовуватися в архітектурі REST. За словами "дядька Боба" Роберта К. Мартіна , архітектура полягає в намірі, а задумом архітектури REST є від'єднання клієнтів від серверів, щоб сервери могли вільно розвиватися в майбутньому, не боячись їх зламати клієнтів. Це, на жаль, вимагає великої дисципліни, оскільки так легко запровадити з'єднання або додати швидкі рішення, щоб виконати роботу та продовжувати роботу. Як вказував Джим Вебер в архітектурі REST, ви, як постачальник послуг, повинні намагатися розробити протокол додатків домену, подібний текстовій комп'ютерній грі 70-х років, за якою дотримуватимуться клієнти, поки вони не закінчать процес.
На жаль, багато так званих API "REST" насправді - це все, окрім цього. Ви бачите обмін даними на базі JSON, які визначені в специфічній зовнішній документації API, яку, як правило, важко динамічно інтегрувати. Формат, яким повинен виглядати запит, також жорстко кодується у зовнішній документації, що призводить до безлічі впровадження інтерпретації URI для повернення попередньо визначених типівзамість того, щоб використовувати якийсь загальний формат представлення, який узгоджується заздалегідь. Це не дозволяє серверам змінюватися, оскільки клієнти тепер очікують отримання певного формату даних (зверніть увагу, не формат подання!) Для попередньо визначених URI. Цей власний обмін форматом даних також запобігає взаємодії клієнтів з іншими API, оскільки "формат даних" зазвичай припливає до конкретного API. Ми знаємо цю концепцію з минулих часів із технологій RPC, таких як Corba, RMI або SOAP, які ми засуджуємо як якось злі, навіть якщо Peppol перейшов до неї знову, замінивши AS2 на AS4 як протокол передачі за замовчуванням, як нещодавно.
Що стосується власне заданого питання, передача даних у форматі CSV - це не що інше, як використання application/x-www-form-urlencodedпредставлення чи подібних матеріалів. Джим Вебер дав зрозуміти, що врешті-решт HTTP - це лише транспортний протокол, домен додатка якого - передача документів через Інтернет . Клієнт і сервер повинні принаймні обидва підтримувати, text/csvяк визначено в RFC 7111 . Цей файл CSV може бути згенерований як наслідок обробки типу носія, який визначає елементи форми, цільовий елемент або атрибут для надсилання запиту, а також метод HTTP для завантаження конфігурації.
Існує кілька типів медіа, які підтримують такі форми, як HTML , HAL Forms , півформа , іон або гідра . На даний момент я не знаю типу носія, який автоматично може кодувати вхідні дані text/csvбезпосередньо, отже, можливо, потрібно буде визначити і зареєструвати в реєстрі засобів масової інформації IANA .
Гадаю, завантаження та завантаження всього набору параметрів не повинно бути проблемою. Як було сказано раніше, цільовий URI не має значення, оскільки клієнт просто використовуватиме URI для отримання нового вмісту для обробки. Фільтрування за датою роботи також не повинно скласти труднощів. Однак тут сервер повинен клієнт з усіма можливостями, які клієнт може просто вибрати. В останні роки розвивалися GraphQL і RestQL, які вводять мову, подібну SQL, яка може бути націлена на певну кінцеву точку, щоб отримати відфільтрований відповідь. Однак у справжньому сенсі REST це порушує ідею, що стоїть за REST як а) GraphQL, тобто використовує лише єдину кінцеву точку, яка певним чином перешкоджає оптимальному використанню кешування, і b) вимагає знань про доступні поля вперед, що може призвести до введення зв'язку клієнтів до базової моделі даних ресурсу.
Активізація або деактивація певних параметрів конфігурації - це просто питання запуску гіпермедіа-елементів керування, які забезпечують це. У формах HTML це може бути проста прапорець або багаторядковий вибір у списку чи іншого виду. Залежно від форми та методу, який він визначає, він може потенційно надіслати всю конфігурацію через PUTабо бути розумним щодо зроблених змін та виконати лише часткове оновлення через PATCH. Останнє вимагає, в основному, калькулятор подання змін до оновленого та подає сервер з необхідними кроками для перетворення поточного представлення в потрібне. Відповідно до специфікації PATH, це повинно бути виконано в рамках транзакції, так що застосовуються всі або жоден з кроків.
HTTP дозволяє та заохочує сервер попередньо перевірити отриманий запит перед застосуванням змін. Для PUT специфікація говорить:
Сервер-джерело ПОТРІБНО перевірити, чи представлення PUT відповідає будь-яким обмеженням, які має сервер для цільового ресурсу, які не можуть або не можуть бути змінені PUT. Це особливо важливо, коли сервер-джерело використовує внутрішню інформацію про конфігурацію, пов'язану з URI, щоб встановити значення для метаданих представлення в GET-відповідях. Якщо представлення PUT суперечить цільовому ресурсу, сервер-джерело ДОЛЖЕН би або зробити їх послідовними, трансформуючи представлення або змінивши конфігурацію ресурсу, або відповісти відповідним повідомленням про помилку, що містить достатню інформацію, щоб пояснити, чому представлення непридатне. Запропоновано коди статусу 409 (конфлікт) або 415 (непідтримуваний тип медіа),
Наприклад, якщо цільовий ресурс налаштований завжди мати тип вмісту "text / html", а представлення, яке PUT, має тип вмісту "image / jpeg", сервер-джерело повинен виконати один із:
а. перенастройте цільовий ресурс для відображення нового типу медіа;
б. перетворити представлення PUT у формат, відповідний формату ресурсу, перш ніж зберегти його як новий стан ресурсу; або,
c. відхиліть запит з відповіддю 415 (Непідтримуваний тип медіа), що вказує, що цільовий ресурс обмежений "текстом / html", можливо, включає посилання на інший ресурс, який був би придатною ціллю для нового представлення.
HTTP не визначає, як саме метод PUT впливає на стан початкового сервера, що перевищує те, що може бути виражено наміром запиту агента користувача та семантикою відповіді сервера-джерела. ...
Для підведення підсумків цієї публікації слід або використовувати наявний тип носія, який дозволяє навчити клієнта необхідним або підтримуваним вхідним параметрам, цільовому розташуванню, на яке потрібно відправити запит, операції, яку потрібно використовувати, а також введіть носій запит має бути відформатований або визначити свій власний, який ви реєструєте в IANA. Останнє може знадобитися, якщо ви хочете перетворити вхідtext/csvа потім завантажте представлення CSV на сервер. Перевірка повинна відбутися до того, як зміни будуть застосовані до ресурсу. Фактичний URI не повинен мати значення для клієнтів, крім того, щоб визначити, куди надсилати запит, і, як такий, можна вільно обирати вас, виконавця послуги. Виконуючи ці кроки, ви в значній мірі отримуєте свободу змінювати свою сторону сервера в будь-який час, і клієнти не будуть ламатися як наслідок, якщо вони підтримують використовувані типи медіа.