5 кроків до створення успішного api

Це природа розробки програмного забезпечення. Розробники створюють програмне забезпечення з урахуванням кінцевого користувача. Це здається досить простим, але іноді ці користувачі також є розробниками. Для них речі не потрібні. Їм навіть не потрібна простота. Все, що вони хочуть, - це доступ - спосіб інтегрувати програмне забезпечення у своє. Тут надходить API (інтерфейс програмування додатків). Я сподіваюся виділити п’ять кроків, які можна зробити для створення успішного API.

Роби своє домашнє завдання

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

Існує багато різних технологій, але більшість API, які ви побачите, будуть використовувати або інтерфейс RESTful, або SOAP. Якщо ви перешкоджаєте, який інтерфейс API ви збираєтесь використовувати, я б запропонував скористатися RESTful підходом за допомогою протоколу HTTP. Це простіше, ніж SOAP, на даний момент він більш популярний, і розпочати його буде простіше при використанні програмного продукту на базі веб-сторінок.

Будьте послідовними

Одне з речей, яке розробники цінують найбільше - це послідовність. Це включає, серед іншого, адресність, введення аргументів, формати виводу та обробку помилок.

При використанні підходу RESTful існує багато різних схем іменування URI. У кожного є свої прихильники, тому просто виберіть одного і дотримуйтесь його. Те саме стосується вхідної та вихідної структури. Більшість API підтримують використання XML та JSON як форматів вводу та виводу. Я б запропонував підтримати обидва, але вибрати формат за замовчуванням.

Для введення даних, ваші вимоги до введення повинні бути названі послідовно і мають мати сенс у контексті виклику API, який ви здійснюєте. Для виводу переконайтеся, що ви використовуєте загальні схеми структури даних. Якщо ви завершуєте вихід одного виклику API в a Тег XML, подумайте про те, як це робити з іншими дзвінками.

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

Замість довільного прапора, який вказує статус виклику, для позначення успішності запиту може використовуватися стандартний код статусу "200 ОК", тоді як код статусу "400 поганий запит" може бути використаний для означення того, що запит був неправильно сформований. Існує досить багато кодів статусу HTTP, які можна використовувати в різних ситуаціях.

Використовуйте OAuth

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

OAuth надає багато переваг щодо аутентифікації сторонніх імені користувача / пароля. Перш за все, клієнт ніколи не має доступу до облікових даних користувача. Користувач перенаправляється на ваш сервер, коли він або вона входить. Після входу користувача на ваш сайт, він або вона переспрямовується назад до клієнта, де клієнт отримає маркер доступу для використання у майбутніх запитах до захищених ресурсів.

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

Почніть рано

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

Напишіть хорошу документацію

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

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

Щоб закріпити свою документацію, обов'язково включіть один або два приклади загальних сценаріїв вводу та виводу для кожного виклику API.

Розробка API: Нехай це буде просто

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