API Vocabulary for Backend Developers: REST, GraphQL, and gRPC (англійською)

Розробники обговорюють API в переглядах дизайну, переглядах коду, технічних інтерв’ю і зустрічах з клієнтами. Незалежно від того, розробляєте ви нову службу, переглядаєте договір API колеги або пояснюєте ваші рішення архітектору рішень, знати точний англійський словник для REST, GraphQL і gRPC є обов’ язковим. У цьому довіднику наведено терміни і фрази, які використовуватиметься у контексті.

REST API Vocabulary (англ.)

REST (Representational State Transfer) залишається найпоширенішим стилем API. Його словник широко використовується в описах робіт, технічних інтерв’ю і документації API.

Endpoint — певна адреса URL, яка представляє ресурс або дію у API. « Кінечна точка /users/{id} повертає профіль для вказаного користувача. »

** Ресурс ** — сутність або об’ єкт, який виставляє API. У REST ресурси є іменниками: /orders, /products, /users. “RESTful дизайн організовує API навколо ресурсів, а не дій — використовуйте /orders замість /createOrder.”

** Метод / дієслово HTTP ** — GET, POST, PUT, PATCH, DELETE. Кожен метод передає намір. « Ми скоріше використовуємо PATCH, ніж PUT для часткових оновлень, оскільки PATCH семантично більш відповідний, коли ви змінюєте лише одне поле. »

** Код стану ** — тризначний код відповіді HTTP, який вказує на результат запиту. Поширені коди: 200 OK, 201 Created, 204 No Content, 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict, 429 Too Many Requests, 500 Internal Server Error.

** Вміст ** — тіло даних запиту або відповіді, зазвичай JSON або XML. « Вміст запиту POST має містити поля userId і amount. »

** Ідемотентна ** — операція, яка дає однаковий результат, незалежно від того, виконується вона один раз або багато разів. GET, PUT і DELETE є ідемпотентними; POST — ні. « Ми обирали PUT замість POST для цієї операції саме тому, що ідемпотентність важлива — клієнти можуть повторити спробу після закінчення часу очікування. »

** Обмеження швидкості ** — обмеження кількості запитів, які клієнт може надати за певний проміжок часу. « API встановлює обмеження швидкості 1000 запитів на хвилину на ключ API; клієнти, які перевищують цю межу, отримують відповідь 429. »

** Розділення на сторінки ** — розділення великих збірок на сторінки. Поширені стратегії: засноване на зміщенні ( ?page=2&limit=20 ), засноване на курсорі або засноване на набірі клавіш. « Для цієї кінцевої точки подачі ми використовуємо сторінкування за допомогою курсора, щоб забезпечити послідовність результатів навіть у разі додавання нових елементів між запитами. »

** Версії ** — керування змінами API з часом без руйнування існуючих клієнтів. Поширені підходи включають версії URL ( /v1/users ) і версії заголовків. « Ми відкидаємо головну версію лише за порушення змін; додаткові зміни є зворотньо сумісними. »

Словник граматики

GraphQL — мова запитів для API, розроблена Facebook (Meta). Його словник відрізняється від REST і важливо знати про ролі в сучасній інженерії продукту.

** Запит ** — операція читання у GraphQL, яка повертає дані. На відміну від REST, один запит GraphQL може отримати дані з декількох ресурсів за один запит. « Клієнт надсилає один запит з запитом на ім’ я користувача, його останні п’ ять замовлень і стан кожного з замовлень. »

** Мутація ** — операція запису у GraphQL (створення, оновлення або вилучення). « Ми визначили мутацію createOrder, яка приймає ідентифікатори продуктів і кількості і повертає новий ідентифікатор замовлення. »

** Розв’ язувач ** — функція на сервері, яка обробляє певне поле у запиту або мутації GraphQL. Кожне поле у схемі відповідає розв’ язувачу. « Розв’ язувач user.orders викликає базу даних для отримання всіх команд, пов’ язаних з цим ідентифікатором користувача »

** Schema ** — визначення системи типів, яке описує всі можливі запиту, мутації, підписки і їх типи повернення у API GraphQL. Написано мовою визначення схем (SDL). « Схема є договором між командами інтерфейсу і сервера; будь- які зміни до неї потребують обговорення. »

** Фрагмент ** — частина запиту GraphQL, яку можна використовувати повторно, і яку можна спільно використовувати у декількох запиту, щоб уникнути повторення. « Ми видобили поля продукту у фрагмент, щоб його можна було використовувати повторно у запиту на список продуктів і запиту на відомості про продукт. »

** Проблема N+1 ** — проблема швидкодії, коли запит викликає один виклик бази даних для батьківського об’ єкта, а потім один додатковий виклик для кожного дочірнього об’ єкта, замість отримання всіх пов’ язаних даних у одному запиту. Зазвичай, цю проблему розв’ язують за допомогою DataLoader. « Ми спостерігали значну затримку у розв’ язанні замовлень через проблему N+1; пакетне оброблення DataLoader зменшило її на 90% »

Словник гРПЦ

gRPC — це високопродуктивний Remote Procedure Call framework, розроблений Google. Він широко використовується для внутрішнього обміну даними між службами.

** Proto / Protocol Buffers ** — мова визначення інтерфейсу (IDL), яку використовують для визначення контрактів служб gRPC і схем повідомлень. Збірка коду на декількох мовах. « Ми визначаємо всі наші типи повідомлень і інтерфейси служб у файлах .proto; сформований код автоматично обробляє серіалізацію »

** Визначення служби ** — еквівалент специфікації API gRPC, визначений у файлі .proto. У ньому наведено список методів RPC, які використовує служба, а також типи повідомлень запит/ відповідь для кожного з них. « Визначення служби є нашим договором; команди сервера і інтерфейсу погоджуються на нього перед тим, як будь- яка зі сторін розпочне реалізацію »

** Струмування ** — gRPC підтримує чотири шаблони зв’ язку: унарний (один запит, одна відповідь), потокове перенесення даних сервера, потокове перенесення даних клієнта і двостороннє потокове перенесення даних. « Ми використовуємо потокове перенесення даних сервера для подачі подій у реальному часі, отже клієнт отримує оновлення без опитування »

** Термін / тайм- аут ** — у gRPC клієнти вказують термін, до якого вони очікують відповіді. Якщо сервер не відповість учасно, клієнт отримає повідомлення про помилку DEADLINE_ EXCEEDED. « Завжди встановлюйте термін для викликів gRPC; без цього, повільна служба нижнього рівня може призвести до того, що все дерево викликів буде зависати на неопределенный час. »

** Перехоплювач ** — середнє програмне забезпечення, яке виконується перед або після виклику gRPC на стороні клієнта або сервера, використовується для ведення журналу, автентифікації або визначення показників. « Ми додали перехоплювач на стороні сервера для ведення журналу назви методу, коду стану і тривалості кожного виклику RPC. »

Приклади слів у контексті

1. «Ми розробили кінцеву точку платежу, щоб бути ідемпотентною, приймаючи ключ ідемпотентності, створений клієнтом; якщо клієнт повторить спробу після тайм-аута, наш сервер виявить дублікат ключа і поверне оригінальну відповідь без обробки платежу двічі»

2. «Перехід від REST до GraphQL вилучив проблему надмірного завантаження в мобільному додатку — клієнти тепер запитують саме ті поля, які їм потрібні, а не отримують великий об’єкт JSON і відкидають більшість з них»

3. «Кожен розв’язувач у нашому шарі GraphQL має строгий тайм-аут; якщо виклик бази даних триває довше, ніж 200 мс, розв’язувач повертає частковий результат, а не блокує весь запит»

4. «Наші внутрішні служби спілкуються через gRPC; визначення .proto сервісу зберігаються в спільному сховищі і обробляються з такою ж жорсткістю, як і публічний контракт API — пошкодження змін вимагає періоду застарівання»

5. «При обговоренні версії API, я завжди розрізняю між додатковими змінами, які є зворотньо сумісними і не вимагають версії, і змінами, такими як видалення поля або зміна коду стану, які вимагають збільшення головної версії»

На практиці: Навігація нюансів — перспектива розробника

Будем честны. Як розробник, ви розумієте * концепції *. Ви можете дізнатися про ідею RESTful API, як побудувати запит GraphQL або переваги швидкодії gRPC. Але переклад цих ідей на чітку, точну англійську для комунікації - перегляд коду, обговорення Slack, описи PR - це те, де все стає складним, особливо коли ваша перша мова не англійська. Це не просто про те, щоб знати * що * ви робите; це про те, щоб сформулювати * чому *, і продемонструвати професійне розуміння термінології.

Однією з поширених проблем є надмірне спрощення. Молодший розробник може сказати щось на зразок: « Я зробив запит GET, щоб отримати дані ». Хоча це технічно правильно, але у цьому випадку втрачається важливий контекст. Рецензент може відповісти: «Чи можете ви розібратися, чому ми використовуємо запит GET тут? Враховуючи потенціал для цієї кінцевої точки, щоб бути викликаним неодноразово, чи ви розглядаєте idempotentia - забезпечення того, що декілька ідентичних запитів мають такий самий ефект, як один?” Це не про критику; це про тиск на ясність і найкращі практики. Аналогічно, опис запиту GraphQL можна скоротити до « Я запитав дані користувача ». Краще було б описати його так: « У запиту використовується вкладений селектор полів для отримання інформації про адресу користувача з об’ єкта його профілю, що забезпечує отримання лише того, що дійсно потрібно для поточної дії ». Використання точної мови показує, що ви продумали всі наслідки вашого вибору дизайну.

Інша часта проблема виникає з поясненням різниць між технологіями. Уявіть, що ви пишете PR-опис gRPC: «Ця служба використовує gRPC, тому що вона швидка». Хоча це і правда, це не передає повної картини. Ефективнішим поясненням було б: «Ми прийняли gRPC, щоб використати його формат двійкового протоколу і підтримку HTTP / 2, що призвело до зменшення витрат і поліпшення продуктивності в порівнянні з RESTful JSON-загрузками - особливо вигідно для цього потоку даних великого обсягу». Зверніть увагу на тонкі відмінності в термінології; «запит» проти «запит», «кінцева точка» проти «операція», всі вони сприяють більш нюансованій і професійній дискусії.

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

Ось приклад використання curl для перевірки кінцевої точки gRPC:

curl -d '{}' -X POST --insecure http://localhost:50051/v1/users

Ця команда показує простий запит POST до служби gRPC, підкреслює використання буферів протоколу і необхідність безпечного транспортування (--insecure — хоча у виробничих умовах ви майже напевно використовуватимете TLS). Це невеликий приклад, але він ілюструє, як навіть здаються простими інструменти є частиною більшої, більш складної комунікаційної екосистеми.