Розуміння основ роботи API і REST API – короткий вступ

 

 

Існує велика ймовірність того, що ви раніше стикалися з терміном REST API, але не зовсім розуміли, про що йде мова? Що таке REST API, як ним користуватися, і що це може вам дати? Сьогоднішня стаття являє собою введення в концепції і можливості REST API: ми розглянемо основи API, для чого ми можемо їх використовувати, розуміння дизайну проектування, а також основи їх захисту. З цієї статті ви дізнаєтеся той мінімум, який дозволить вам читати документацію API і ефективно використовувати її.

 

 

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

REST – це стиль архітектури API для розподілених систем. REST визначає, як дані надаються клієнту в зручному для нього форматі. Обмін даними відбувається у форматі JSON або XML (хоча сьогодні більш популярний формат JSON).

 

 

Розуміння того, як дані обмінюються через Інтернет

Обмін даними в Інтернеті відбувається за допомогою TCP/IP (протокол управління передачею/інтернет-протокол). TCP/IP – це набір протоколів зв’язку, який описує, як взаємодіє величезна кількість комп’ютерів, підключених до Інтернету.

TCP/IP забезпечує наскрізний зв’язок, який визначає, як дані обмінюються через Інтернет, як дані розбиваються на пакети, як пакети кодуються, адресуються, маршрутизуються і приймаються в місці призначення. Думайте про це як про гігантську компанію по доставці пошти, яка здатна доставляти ваші посилки в будь-яку точку світу неймовірно швидко. TCP/IP визначає правила для упаковки кожної з посилок, щоб вони могли дістатися до потрібної людини без плутанини.

TCP/IP використовує стандартну модель зв’язку клієнт-сервер, коли клієнт (комп’ютерний пристрій) запитує ресурс у сервера (можливо, набагато більшого комп’ютерного пристрою у віддаленому місці). З’єднання з використанням TCP/IP не зберігають стани – запит від клієнта до сервера розглядається як новий, сервер ніколи не запам’ятовує клієнта. Це звільняє ресурси на сервері, щоб зробити його швидше, і він швидше відповідав на кілька запитів.

 

 

Розуміння того, як API дозволяють додаткам спілкуватися один з одним

API-інтерфейси схожі на TCP/IP для додатків. Вони визначають, як додатки взаємодіють і обмінюються даними між собою. Як і TCP/IP, REST API-інтерфейси не мають стану. Всі запити, що використовують API, повинні містити якомога більше інформації, щоб сервер міг ідентифікувати клієнта.

API визначає набір правил для взаємодії однієї програми з іншою. Більшість API мають належну документацію, яка також визначає характер і структуру відповіді, яку вони відправляють, коли ви робите запит. Вони також вказують необхідну інформацію, яку запитуючий додаток повинен надати для успішного запиту до API.

По суті, REST API-інтерфейси працюють приблизно так само, як і стандартні запити TCP/IP, за винятком того, що тут немає клієнтів і серверів, а є тільки два додатки, які взаємодіють один з одним.

 

 

Коротко про різні шаблони API

Існує кілька шаблонів для розробки API. Ці шаблони мають свою історію, різні вимоги і створюють різні можливості для користувачів. Ці конструкції так чи інакше пов’язані один з одним, тому ми побачимо багато місць, де вони дуже схожі. Розуміння їх допоможе вам прийняти рішення про те, які з них використовувати для вирішення ваших конкретних завдань.

 

Стиль тунелювання

Тунелювання працює як система віддалених викликів процедур (RPC), організованих в форматі повідомлень XML. RPC сам по собі є дійсно старою технологією, яка найкраще підходить для передачі команд і процедур. SOAP в деяких випадках використовує тунелювання.

 

 

SOAP – Простий протокол доступу до об’єктів

Можна стверджувати, що SOAP є протоколом зв’язку, а не архітектурою/шаблоном API, тому що він визначає свій набір правил зв’язку та протоколів безпеки і таке інше. SOAP API-інтерфейси більш затратні, ніж їх аналоги, але також мають і свої переваги. Вони забезпечують більшу безпеку при розробці великомасштабних корпоративних додатків.

Вибір SOAP ґрунтується на функціях, пов’язаних з безпекою, транзакціями і відповідністю набору ACID (атомарність, узгодженість, ізольованість, довговічність), що робить його більш привабливим для додатків корпоративного масштабу.

 

 

REST

REST – це дійсно API-інтерфейс «веб-сервісів», що ставить його на протилежну сторону SOAP. REST API засновані на URI (уніфікований ідентифікатор ресурсу) і протоколі HTTP. REST API можуть обмінюватися даними в форматі JSON або XML, хоча більшість API REST відправляють дані у вигляді JSON.

При створенні системи з мінімальними міркуваннями безпеки, але з високими вимогами до швидкості, REST є відмінним вибором. REST API-інтерфейси мають менше вимог до безпеки, покращують сумісність з клієнтом браузера, краще відкриття, працездатність даних і масштабованість – речі, які дійсно застосовні до веб-сервісів.

 

 

Що таке REST API

Припустимо, ви намагаєтеся знайти якесь відео на YouTube. Ви відкриваєте YouTube, набираєте слово в поле пошуку, натискаєте Enter, і ви бачите список відповідних відео. REST API працює аналогічним чином. Ви шукаєте щось і отримуєте список результатів від служби, яку ви запитуєте. Інший приклад: ви як розробник викликаєте Instagram API, щоб отримати конкретного користувача (ресурс), API повертає вам стан цього користувача, включаючи його ім’я, кількість постів, які користувач опублікував в Instagram, скільки у нього підписників, і таке інше.

Кожен URL називається запитом, а відправлені вам дані називаються відповіддю.

 

Анатомія запиту до API

Важливо знати, що запит складається з чотирьох речей:

• Кінцева точка (endpoint)
• Метод (GET, POST, PUT, або DELETE)
• Заголовки (HTTP заголовки, повний список тут)
• Дані (або тіло; відповідь, що була надіслана)

 

Кінцева точка (або маршрут) – це URL, який ви запитуєте. Це відправна точка API, який ви запитуєте. Наприклад, кореневою кінцевою точкою API Github є https://api.github.com, а кореневою кінцевою точкою Twitter API є https://api.twitter.com.

 

 

REST API – визначення дизайну. Рекомендації з проектування

Як приклад уявіть, що вам потрібен сервіс для контролю запасів автомобілів. Нижче проста таблиця основних даних REST API, які ви можете зробити для такого додатка:

Ресурс	GET (читання)	POST (створення)	PUT (оновлення)	DELETE (видалення)
/cars	Повертає список всіх автомобілів	Створити новий автомобіль	Масове оновлення автомобілів (використовується рідко)	Видалити всі автомобілі (ймовірно, вам не слід це реалізовувати)
/cars/1955	Повертає певний автомобіль	Метод не дозволений (405)	Оновлює конкретний автомобіль	Видаляє певний автомобіль

 

 

 

Метод GET і параметри його запиту не повинні змінювати стан. Уникайте проектування кінцевих точок виду:

GET /cars/1955?avaliable=true
GET /cars/1955/has-finished

 

Це дуже погано для вашого застосунку. Якщо бот пошукової системи або будь-який веб-сканер коли-небудь заволодіють цим URL…

Якщо вам потрібно змінити стан, використовуйте POST, PUT або DELETE, як в таблиці вище.

 

 

Використовуйте підресурси для відносин

Припустимо, ви розробляєте соціальну мережу, в якій користувачі ведуть блоги, тому ви повинні встановити приблизно такі відносини:

GET /users/1955/blogs

 

Це повинно повернути всі публікації користувача. Якщо ви хочете отримати певний запис, ви можете зробити наступне:

GET /users/1955/blogs/150

 

 

Обробляйте помилки за допомогою HTTP-кодів стану

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

Тут ви знайдете повний список HTTP-кодів стану сервера.

 

 

Забезпечуйте нумерацію сторінок, сортування і фільтрацію

Це, сподіваємося, зрозуміло. Ваша програма, швидше за все, буде мати величезне сховище інформації. Неправильним буде виклик ендпоїнтів, який поверне всі автомобілі і надішле вам 100 000 автомобілів одночасно. Перевантаження вашого сервера буде божевільним, і ви швидко спалите свої ресурси.

Повинно бути сортування авто по маркам, рокам випуску і країні-виробнику. Також повинна бути можливість сортування за алфавітом або по якомусь іншому критерію. Це дрібниці, які поліпшать те, як буде використовуватися ваш API.

 

 

Основи безпеки API

Ви не повинні повністю ігнорувати безпеку. Ми розглянемо способи безпеки API з двох точок зору: аутентифікація і авторизація.

 

Аутентифікація

Це пов’язано з перевіркою особистості людини, що намагається отримати доступ до вашого API. Це можна зробити декількома способами. У простій формі це буде поєднання імені користувача, адреси електронної пошти та пароля. Для API це, швидше за все, буде пов’язано з використанням токену безпеки, який ідентифікує користувача. У більш складних сценаріях пари ключ/секрет часто використовуються для інтеграції однієї програми до іншої.

 

Авторизація

Цей крок відбувається після аутентифікації, і він відповідає на питання «Що вам дозволено робити». Авторизація зручна, коли ви проектуєте кінцеві точки для доступу до даних, які є або дуже специфічними для конкретної людини, або конфіденційною інформацією, доступ до якої може отримати тільки визначений набір людей.

 

 

 

Короткий висновок

У цьому уроці ми розглянули REST API-інтерфейси і кілька моментів, які слід враховувати при їх розробці. Ми коротко розглянули різні шаблони API, трохи докладніше ми зупинилися саме на REST API.

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