REST API

Історія

REST розшифровується як Re презентаційний протокол передачі даних S tate T. Рой Філдінг визначив REST у своїй кандидатській дисертації у 2000 році.

Що таке REST API?

REST був розроблений для забезпечення єдиного інтерфейсу для

  • Визначення ресурсів
  • Маніпулювання ресурсами
  • Самоописові повідомлення
  • Використання Hypermedia як двигуна стану програми (HATEOS)

Кращі практики

Основи

Метод || //api.co/v2/cars || //api.co/v2/cars/1234

  • ОТРИМАТИ || Перелічіть усі машини || Витягніть індивідуальний автомобіль
  • ПОШТА || Створити нову машину || Помилка
  • ПОСТАВИТИ || Замінити колекції автомобілів || Замініть машину на ідентифікатор 1234

    з новим

  • ВИДАЛИТИ || Видалити всі машини || Видалити машину з ідентифікатором 1234

Зверніть увагу, що під час операцій PUT або клієнт, або сервер можуть генерувати ідентифікатори

Іменники хороші Дієслова погані

  • Використовуйте іменники для позначення ресурсів , таких як cars, і fruitsт.д.
  • Використовуйте дієслова для оголошень про дії convertMilesToKms,getNutritionalValues

Одиниця чи множина?

Використовуйте правильну граматику для декларації

Уникайте/person/145

Віддайте перевагу/people/154 Припущенню, щоб повернути 154-ту людину зі списку людей

Кейси використання

Використовуйте будь-яку з наведених нижче схем і будьте послідовними!

Стилі корпусу Приклад: UpperCamelCase //api.fintech.cp/DailyTransactions/TodaylowerCamelCase //api.fintech.cp/dailyTransactions/todaysnake_case//api.fintech.cp/daily_transactions/today

Відносини та ресурси

  • Ресурси можуть мати one-to-many, many-to-many, many-to-oneвідносини і т.д. Mapping їх правильно має вирішальне значення.

Картування " один до багатьох"

Наприклад, Tickets/145/messages/4пропонує співвідношення "один до багатьох" між ticketsі messages. Значення 1квитка має Nповідомлення. Повідомлення не є автономним ресурсом. Ви не можете мати /messages/4.

Картографування багатьох до багатьох

Наприклад, /usergroups/345/users/56пропонує вибрати 345-ю групу користувачів і отримати користувача з ідентифікатором 56. Однак один користувач може бути в декількох, usergroupsтобто /usergroups/209/users/56також є дійсним. У такому випадку так для розділення депедентного ресурсу usersна окрему кінцеву точку, наприклад, /users/56і забезпечення зв'язку ресурсів/usergroups/209/users/56

Параметри API

  • PATH : необхідний для доступу до ресурсу, наприклад/cars,/fruits
  • Параметри запиту : необов’язковий фільтр списку Напр/cars?type=SUV&year=2010
  • Тіло : логіка, специфічна для ресурсів. Попередній пошуковий запит. Іноді він може мати як запит, так і тіло.
  • Заголовок : повинен містити глобальні дані або дані про платформу. Наприклад, параметри ключа API, зашифровані ключі для автентифікації, інформація про тип пристрою, наприклад, мобільний телефон або робочий стіл або кінцева точка, тип даних пристрою, наприклад, xml або json. Використовуйте заголовок для передачі цих параметрів

Коди стану HTTP

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

CodesMeaning1xxRequest отримано та зрозуміло. 2xx Дія, яку запитував клієнт, отримана, зрозуміла та запитана. 3xxClient повинен виконати додаткові дії для завершення запиту. Більшість із цих кодів стану використовуються в URL-адресі Redirection.4xxIntended для ситуацій, коли, здається, помилку спричинив клієнт. 5xxСервер не зміг виконати запит.

Трохи більше про 2xx !

  • 201 Ресурс створено. POST/carsповинен повернути HTTP 201, створений ізlocationзаголовком, де вказано, як отримати доступ до ресурсу, наприкладlocation:api.com/cars/124у заголовку

202 - Прийнято

Використовуйте це, якщо завдання величезне для запуску. Скажіть клієнту, що він прийняв запит і обробляє / обробляє / не обробляє корисне навантаження

204 - Без вмісту

Використовується при видаленні DELETE cars/124Повертає відсутність вмісту. Але може також повернутися, 200 OKякщо API має намір надіслати видалений ресурс для подальшої обробки.

Небезпечні 5xx ресурси!

  • 500 Внутрішня помилка сервера
  • Час очікування шлюзу 504 . Сервер не отримав своєчасну відповідь

Менш відомий 4xx припускає, що ви передаєте неправильний параметр. Також може передавати неправильну інформацію. Напр

DELETE /cars/MH09234

returns 4xx or message Expecting int car id /car/id got string car/MH09234