Диван - найкращий спосіб REST (це GraphQL)

Закінчення дебатів REST проти GraphQL раз і назавжди

Активуйте REST API швидко

TL; DR

  • Не вибирайте між REST і GraphQL - автоматично створюйте повністю RESTful API з вашої реалізації GraphQL (з бібліотекою та одним рядком коду)
  • Отримайте більшу частину переваг GraphQL на бекенді та фронті, використовуючи та експонуючи REST
  • Підтримуйте всіх своїх існуючих клієнтів за допомогою REST, вдосконалюючи свій запасний стек за допомогою GraphQL
  • Створіть власні, ідеально орієнтовані на клієнта кінцеві точки REST для вашого фронта, просто вказавши маршрут та додавши запит
  • Перестаньте сперечатися про REST проти GraphQL. Використовуйте GraphQL, генеруйте REST та отримуйте найкраще з обох
  • І навпаки (REST to GraphQL) ви не отримаєте кращого з обох країн світу, але менш потужного, складніше підтримувати реалізацію сервера з деякими перевагами GraphQL. Це хороший і швидкий старт для міграції ..

Чекати, що!?

Було написано багато статей про плюси та мінуси API API та GraphQL та про те, як вирішити, який з них використовувати. Я не збираюся їх повторювати тут ..

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

Я працюю з API REST, GraphQL та SOAP багато років. Тому я подумав, чому б не придумати список тих випадків використання, а для кожного з них перевірити - що ти не можеш зробити у GraphQL, що ти можеш робити з REST і що ти не хочеш робити з GraphQL та ви б віддали перевагу ВІДНОС.

Створивши цей список, у мене раптом з’явилася думка - що робити, якщо з’явився інший варіант - що робити, якщо мій потужний сервер GraphQL міг просто генерувати для мене REST API?

Тоді я міг би отримати найкраще з обох світів!

Чим більше я занурився в ідею та реалізацію, тим більше зрозумів, що це не тільки те, що ми можемо створити обидва типи API, але навіть якщо ми просто хочемо виставити API REST, і ніхто з наших клієнтів не використовує GraphQL, GraphQL - це найкращий спосіб створити API REST!

Як вищезазначене речення навіть має сенс ?!

Зазвичай, коли ми (Гільдія) допомагаємо компаніям та організаціям модернізувати свої API, першими, хто зрозумів переваги GraphQL, є розробники інтерфейсів із зрозумілих причин. Але як тільки бекенд-розробники «дістають її», вони стають найбільшими прихильниками технології. Але їм все одно потрібно підтримувати існуючих клієнтів та сторонніх партнерів.

Ось чому ці новостворені API REST отримують багато можливостей та переваг від внутрішньої реалізації GraphQL, що робить розробників бекенда щасливими:

  • Повністю сформована документація, яка завжди актуальна (Swagger, OpenAPI і GraphiQL)
  • Воістину RESTful API з коробки
  • Підписки GraphQL як Webhooks
  • Перевірка даних під час виконання - будьте на 100% впевнені, що отримані дані відповідають структурі схеми та структурі запиту. Ви надсилаєте саме те, що я хочу надіслати, рядок - це рядок, об’єкт має точно такі ж властивості.
  • Створення власної кінцевої точки тепер залежить від вибору назви маршруту та додавання до нього запиту. зроблено. Більше не вручну працювати над створенням та підтримкою конкретних клієнтських кінцевих точок!
  • Використовуйте філософію GraphQL щодо розвитку API за допомогою схем - не більш болючих міграцій API V1 - V2.
  • Використовуйте сучасні технології, до яких легше найняти людей. Такі компанії, як Facebook, Airbnb та інші перейшли до GraphQL. Жоден з них не повернувся назад.
  • Потужність графічних розв'язувачів GraphQL створити вашу реалізацію API замість контролерів MVC, записаних вручну

Що я отримую від розв'язувачів?

  • Простіше перетворити дані, щоб вони відповідали відповіді (GraphQL Schema). Це тому, що у кожної особи є власні розв’язувачі, тому картографування переміщується на менші шматки та повторно використовується у всьому додатку.
  • GraphQL дозволяє легко обмінюватися даними через кожен резолютор, ми називаємо це контекстом.
  • Примушує вас визначати та вирішувати дані висловлюваним способом, що фактично допомагає створити API. Він виконує функції паралельно (функції, які вкладені на одному рівні), обробляє асинхронізацію і в кінці, він відповідає за об'єднання всього цього в один об'єкт, тому вам не потрібно думати про це.

Диван - Використовуйте GraphQL для створення API RESTful

Таким чином ми створили Sofa (призначений для каламбура), бібліотеку з відкритим кодом, яку ви встановите на свій сервер GraphQL, щоб створити повністю RESTful і настроюваний шлюз API. Використовуйте GraphQL для REST.

Підручник "Як"

Створимо короткий покроковий посібник про те, як створити API RESTful.

Крок 1: npm встановіть пакет `sofa-api` та додайте наступний рядок коду:

Крок 2. Перейдіть REST на диван, ви закінчили.

Каміль Кісіела додав диван до реалізації SpaceX GraphQL API Карлоса Руфо, за один комітет.

Перевірте повністю генеровані кінцеві точки REST, живу документацію Swagger, редактор GraphiQL та GraphiQL-Explorer!

До речі, тут ви бачите REST API, сформований поверх API API GraphQL, створений поверх іншого API REST….

Чому ти це зробив!?!?

Поступово переходить зі старих реалізацій REST

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

Але такі реалізації REST є проблематичними (з усіх очевидних причин, які люди вирішили перейти на GraphQL).

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

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

Дайте мені більше деталей

Диван за замовчуванням використовує Express, але ви можете використовувати будь-який інший серверний фреймворк. Диван також є агностиком для впровадження GraphQL-сервера.

Перейдіть на веб-сайт дивану для документації та до сховища Github, щоб повідомити про проблеми та допомогти.

Як працює диван?

Під капотом диван перетворює кожне поле типів запитів і мутацій у маршрути. Перша група маршрутів доступна лише методом GET, з іншого боку мутації отримують POST.

Диван використовує AST GraphQL для створення операції з усіма можливими змінними (навіть з глибоко вкладеними) і точно знає, що потрібно отримати. Пізніше він перетворює тіло запиту в змінні операції та виконує його на схемі. Це відбувається локально, але можливо також використовувати зовнішній сервер GraphQL або навіть Apollo Link.

Зараз у Sofa є вбудована підтримка Express, але цілком можливо використовувати інший фреймворк. Основна концепція залишається точно однаковою, тому лише те, як ми обробляємо запит, відрізняється в різних реалізаціях сервера.

Підписки GraphQL як Webhooks?

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

Моделі / ресурси?

У деяких випадках ви не хочете виставити цілий об'єкт, а лише його ідентифікатор. Як вам це вдається зробити з Диваном? Потрібно мати два запити. Перший повинен повернути одне ціле на основі його ідентифікатора (що було б аргументом), а другий повинен вирішити їх список. Також імена повинні відповідати, наприклад, ресурс під назвою Користувач повинен мати два запити: user (id: ID): User та users: [User]. Приблизно те саме, що ви зробили б із REST.

введіть запит {
  user (id: ID!): Користувач
  користувачів: [Користувач]
}

Перш ніж Sofa створює маршрути, він шукає ці Моделі та реєструє їх, тому при створенні операцій ви не збираєте все, а лише ідентифікатор.

Але що робити, якщо ви хочете отримати цілий об'єкт, але лише в кількох місцях?

Існує варіант, який називається ignore, який дозволяє вам це зробити. Ви просто проходите шлях, яким ви хочете перезаписати поведінку за замовчуванням.

З огляду на схему нижче, ви отримаєте лише ідентифікатор автора.

тип Книга {
  я робив
  назва: Рядок!
  автор: Користувач!
}
тип запиту {
  книга (id: ID!): Книга
  книги: [Книга]
}

З ігноруванням: ['Book.author'] ви отримуєте цілий об'єкт користувача.

диван ({
  ...,
  ігноруйте: ['Book.author'],
})

Swagger і OpenAPI

Завдяки системі типу GraphQL Диван здатний генерувати завжди актуальну документацію для вашого REST API. На даний момент ми підтримуємо Swagger та його специфікацію OpenAPI, але реально прийняти різні характеристики.

Підсумок

sofa-api дозволяє надзвичайно просто створити API RESTful з усіма найкращими методами REST на сервері GraphQL, використовуючи всю його потужність.

Перестаньте витрачати своє життя, сперечаючись про REST vs GraphQL - Будьте продуктивні, отримайте переваги обох світів і рухайтеся у майбутнє розробки API.

Я сподіваюся, що це стане останньою статтею REST vs. GraphQL там…. якщо ви думаєте, що цього не вийде, прокоментуйте випадок використання і давайте спробуйте!

Дякую Камілу Кісіелі, що працював зі мною над цим і робив цю бібліотеку реальністю!

Слідкуйте за нами на GitHub та Medium, ми плануємо випустити ще багато публікацій у найближчі пару тижнів про те, що ми дізналися за допомогою GraphQL за останні роки.