Коротко про мене
Мене звати Зел, я розробник-фрілансер із Сінгапуру. У вільний від роботи час я люблю розбиратися в коді і принагідно публікувати у своєму блозі ті цікавості, які я виявив чи вивчив.
Вступ
Швидше за все вам уже доводилося чути про такий термін, як REST API, особливо якщо ви стикалися з необхідністю отримання даних з іншого джерела (такого як Twitter або GitHub). Але що ж все-таки це таке? Що ми можемо робити з цим і як ми можемо це використовувати?
У цій статті ви дізнаєтеся все про REST API для того, щоб працювати з ними та читати пов'язану з ними документацію.
Що ж таке REST API?
Давайте уявимо, що ви намагаєтеся знайти фільми про Бетмена на YouTube. Ви відкриваєте сайт, вбиваєте у форму пошуку слово «Бетмен», тиснете «Окей» і бачите список фільмів про супергероя. Так само працює і WEB API. Ви шукаєте щось і отримуєте список результатів від ресурсу, до якого здійснюєте запит.
Дослівно API розшифровується як Application Programming Interface. Це набір правил, що дозволяє програмам спілкуватися одна з одною. Розробник створює API на сервері та дозволяє клієнтам звертатися до нього.
REST – це архітектурний підхід, що визначає, як API мають виглядати. Читається як "Representational State Transfer". Цьому набору правил і слідує розробник під час створення свого застосунку. Одне з цих правил каже, що при зверненні до певної адреси ви повинні отримувати певний набір даних (ресурс).
Кожна адреса - маршрут, пакет даних - запит, у той час як результуючий ресурс – відповідь.
Анатомія запиту
Важливо розуміти структуру запиту:
- Маршрут відправки.
- Тип методу.
- Заголовки.
- Тіло (або дані).
Маршрут – це адреса, за якою надсилається ваш запит. Його структура приблизно така:
Root-endpoint - це точка прийому запиту на стороні сервера (API). Наприклад, кінцева точка GitHub - https://api.github.com.
Шлях визначає ресурс, до якого здійснюється запит. Це щось на кшталт автовідповідача, який просить вас натиснути 1 для одного сервісу, 2 для іншого і так далі.
Для розуміння того, які саме шляхи вам доступні, вам слід переглянути документацію. Наприклад, припустимо, ви хочете отримати список репозиторіїв для конкретного користувача на Git. Згідно з документацією, ви можете використати наступний шлях для цього:
Вам слід підставити під пропуск ім'я користувача. Наприклад, щоб знайти список моїх репозиторіїв, ви можете використати маршрут:
Остання частина маршруту – це параметри запиту. Технічно запити не є частиною REST-архітектури, але на практиці зараз все ґрунтується на них. Тож давайте поговоримо про них детальніше. Параметри запиту дозволяють використовувати у запиті набори пар «ключ-значення». Вони завжди починаються знаком питання. Кожна пара параметрів після чого розділяється амперсандом (щось подібне до цього):
Як тільки ви намагаєтеся отримати список репозиторіїв для користувача, ви додаєте ці три опціональні параметри і після чого отримуєте наступний результат:
Якщо ж ви бажаєте отримати список моїх недавно запушених репозиторіїв, вам слід ввести наступне:
Отже, як же зрозуміти, що маршрути робочі? Що ж, настав час перевірити їх на практиці!
Тестування за допомогою Curl
Ви можете надіслати запит за допомогою будь-якої мови програмування. JavaScript може використовувати методи на кшталт Fetch API або JQuery`s Ajax Method. Рубі використовує інше. І так далі.
У цій статті я використовуватиму таку утилітку, як Curl. Справа в тому, що вона вказана в офіційній документації для веб-сервісів. Якщо ви зрозумієте, як використовувати цю утиліту, ви зрозумієте, як працювати з API. Після чого ви можете робити запити будь-якою зручною для вас мовою.
Перед тим, як продовжити, слід переконатися, що Curl встановлений на вашій машині.
Якщо ж він не встановлений, саме час встановити. У такому разі ви отримаєте помилку "command not found".
Для того щоб використовувати утиліту, необхідно ввести наступне (за прикладом):
І як тільки ви підтверджуєте введення, ви отримуєте відповідь (на зразок цього):
Щоб отримати список користувацьких репозиторіїв, вам слід змінити запит за тим же принципом, який був обговорений раніше. Наприклад, щоб отримати список моїх репозиторіїв, вам слід ввести наступне:
Якщо ж ви бажаєте включити параметри запитів, переконайтеся, що ви їх екрануєте. Справа в тому, що без екранування знаки питання і рівності розцінюються системою як спецсимволи і виконання команди відбудеться з помилкою.
Також спробуйте інші команди та зробіть запити! В результаті ви отримуєте схожі відповіді.
JSON
JSON – JavaScript Object Notation – загальний формат для надсилання та прийому даних за допомогою REST API. Відповідь, що відправляється Github, також міститься у форматі JSON.
Зміст об'єкту цього формату приблизно наступний:
Повертаємось до анатомії запиту.
Ви вивчили, що запит складається із чотирьох частин:
- Маршрут відправки.
- Тип методу.
- Заголовки.
- Тіло (або дані).
Тепер давайте спробуємо розібратися з рештою.
Тип методу
Метод позначає тип запиту, який здійснюється; де-факто він є специфікацією операції, яку повинен здійснити сервер. Усього існує п'ять типів запитів:
- GET
- POST
- PUT
- PATCH
- DELETE
GET – використовується для отримання з боку серверу певного ресурсу. Якщо ви здійснюєте цей запит, сервер шукає інформацію та відправляє її вам назад. По суті, він здійснює операцію читання на сервері. Дефолтний тип запитів.
POST – необхідний для створення певного ресурсу на сервері. Сервер створює в базі даних нову сутність та сповіщує вас, чи був процес створення успішним. По суті, це операція створення.
PUT та PATCH – використовуються для оновлення певної інформації на сервері. У такому разі сервер просто змінює інформацію існуючих сутностей у базі даних та повідомляє про успіх виконання операції.
DELETE – як і випливає з назви, видаляє вказану сутність із бази чи сигналізує про помилку, якщо такої сутності в базі не було.
Сам же API дозволяє вказати, який метод має бути використаний у певних контекстних ситуаціях.
GET запит у цьому випадку необхідний, щоб одержати список всіх репозиторіїв зазначеного користувача. Також можна використовувати curl:
Спробуйте надіслати цей запит. Як відповідь ви отримаєте вимогу про аутентифікацію.
Заголовки
Заголовки використовуються для надання інформації як клієнту, так і серверу. Взагалі, їх можна використовувати для багато чого; наприклад, та сама автентифікація та авторизація. На офіційній сторінці MDN можна знайти список доступних заголовків.
Відео курси за схожою тематикою:
Заголовки являють собою пари ключів-значень. Приклад:
Також приклад із використанням curl:
(Примітка: заголовок Content-Type у випадку Github для роботи не є обов'язковим. Це всього лише приклад використання заголовка в запиті, нічого більше).
Для перегляду надісланих заголовком даних можна використовувати наступне:
Тут зірочка відноситься до додаткової інформації, наданої за допомогою curl. > відноситься до заголовків запиту, а <, відповідно, - до заголовків відповіді.
Щоб надіслати інформацію з curl, використовуйте наступне:
Для відправки множинних полів ми можемо використати декілька подібних конструкцій:
Також, якщо необхідно, ви можете розбити ваш запит на декілька ліній для забезпечення більшої читабельності:
Якщо ви знаєте, як розгорнути сервер, ви можете створити власний API та протестувати свої запити. Якщо ж ні, обов'язково спробуйте. Існує безліч інформації, присвяченої цьому.
Якщо ж бажання розгортати свій сервер немає, спробуйте безкоштовну опцію Request bin.
Після чого ви отримаєте адресу, яку спокійно зможете тестувати.
Переконайтеся, що ви створюєте власний request bin, якщо ви хочете протестувати саме ваш запит. Зважайте на те, що дефолтний час існування request bin – 48 годин. Тому ті приклади адрес, які я тут наводжу, на момент прочитання статті давно застаріли.
Тепер спробуйте надіслати деяку інформацію, після чого оновіть свою сторінку.
Якщо все пройде успішно, ви побачите наступне:
За замовчуванням curl відправляє дані так, ніби вони були відправлені за допомогою полів форм. Якщо ви бажаєте надіслати дані через JSON, ваш Content-Type повинен дорівнювати application\json, внаслідок чого вам необхідно відформатувати дані у вигляді JSON-об'єкту.
По суті, це все, що вам необхідно знати про структуру запиту.
Тепер давайте згадаємо про аутентифікацію. Що ж це таке і навіщо вона потрібна?
Аутентифікація
Ви б не дозволили нікому чужому отримати доступ до вашого банківського рахунку без спеціального дозволу, чи не так? За таким же принципом розробники не дозволяють неавторизованим користувачам робити на сервері все, що їм заманеться.
Оскільки POST, PUT, PATCH, DELETE запити змінюють базу даних, розробники повинні завжди бути на варті неавторизованого доступу до них. Проте іноді GET запити також вимагають аутентифікації (наприклад, коли ви хочете переглянути стан вашого банківського рахунку).
У випадку з вебом існує два способи представитися системі:
- Через нік і пароль (базова автентифікація)
- Через секретний токен
Секретний токен дозволяє представити вас системі через соцмережі на кшталт Github, Google, Twitter і так далі.
Тут же я розгляну лише базову автентифікацію.
Для виконання базової аутентифікації ви можете використовувати наступне:
Спробуйте залогінитися під свій профіль за запитом, вказаним вище. Як тільки ви успішно увійдете у свій профіль, ви побачите відповідь "problems parsing JSON".
Чому? Все просто: системі ви представилися, але - от біда - нічого корисного їй не надали. Усі типи запитів потребують певної інформації.
Тепер же давайте поговоримо про статус-коди та можливі помилки.
Статус-коди та можливі помилки
Деякі з повідомлень, наведених вище, якраз і належать до кодів помилок. Логічно, що вони з'являються лише тоді, коли щось іде не зовсім так, як було заплановано. Що ж до статусу кодів, вони дозволяють вам пізнати успіх (або невдачу) під час виконання певного запиту. Бувають статус-коди від 100 до 500+. Загалом їх можна поділити на такі групи:
- 200+: запит успішний
- 300+: запит перенаправлений на інший маршрут
- 400+: помилка на стороні клієнта
- 500+: помилка на стороні сервера
Ви можете відлагодити статус відповіді за допомогою –v або –verbose. Наприклад, я спробував отримати доступ до певного ресурсу без авторизації. Відповідно, я спіймав помилку:
У випадку ж, коли запит невірний через помилку в самій інформації, що передається, ви отримуєте статус-код 400:
Версії API
Безкоштовні вебінари за схожою тематикою:
Час від часу розробники оновлюють свої API. Іноді оновлення можуть бути такими сильними, що розробник бажає здійснити реліз нової версії. У такому випадку, якщо ваш застосунок ламається, це відбувається через те, що ви писали код з урахуванням старого компонента, тоді як новий дещо відрізняється в плані реалізації.
Запросити поточну версію API можна двома шляхами.
- Через маршурт
- Через заголовок
Наприклад Твіттер використовує перший спосіб. На момент написання версія Twitter API була 1.1.
Водночас GitHub використовує інший спосіб:
На закінчення
У цій статті ми розглянули, що таке REST API і як його можна використовувати спільно з curl. Крім того, ви також вивчили, як залогінитись за допомогою запиту і що таке статус-код.
Я щиро сподіваюся, що ця стаття дозволила вам підвищити свій рівень загальних і не дуже знань щодо такого важливого аспекту веб-розробки. Буду радий будь-яким вашим коментарям тут.
Автор перекладу: Євген Лукашук
Ще більше матеріалів на цю тему:
ASP.NET Core Web API. Практичний курс
Статті за схожою тематикою
