Создаем мощный API на Node.js, GraphQL, MongoDB, Hapi и Swagger

9
7517
Добавить в избранное

Написанию API посвящено много публикаций, и большинство из них слишком мудреные. В этой статье мы попробуем сделать мощный API простым и понятным.

Мы будем создавать очень гибкий и мощный API на базе Node.js и GraphQL с документацией, созданной на Swagger.

Основой API будет Hapi.js – малоизвестный фреймворк, позволяющий создавать логику приложения, не отвлекаясь на архитектуру, а также получить больший контроль над процессом, нежели может предложить, например, Restify или Express. Рекомендуем посмотреть видеоурок по этому фреймворку для приобретения дополнительных знаний и получения общего представления о системе:

Наш проект предусматривает интеграцию с клиентской частью на React, Vue или Angular.

Нам понадобится:

  • Установленный Node.js и MongoDB.
  • Базовые знания по JavaScript (если их недостаточно, вот вам прекрасный курс для саморазвития).
  • Терминал и текстовый редактор.

Начнем

Откройте терминал и создайте проект. Внутри каталога проекта мы инициализируем Node проект.

Далее нам нужно установить сервер Hapi вместе с зависимостями. Для этого можно использовать как Yarn, так и NPM.

Вторая зависимость – это nodemon. Он будет автоматически перезагружать наш сервер, когда будут внесены какие-либо изменения.

Настройка Hapi очень проста – создайте в корневой директории файлик index.js и наполните его следующим образом:

  • Первое, что мы делаем – подключаем зависимости от hapi.
  • Во-вторых, добавляем константу server, которая создает новый экземпляр нашего сервера Hapi. В качестве аргументов мы передаем объект с параметрами port и host.
  • В-третьих, мы создаем метод init, внутри которого, у нас есть еще один асинхронный метод (server.start()), запускающий сервер.

Если у вас возникают трудности с async await, рекомендуем посмотреть видео на эту тему:

Посмотрим, что получилось:

Если перейти по этой ссылке

мы должны увидеть следующее:

Создаем мощный API

Результат очевиден, т. к. не хватает обработчика и роутов, которые мы добавим ниже. А пока научим nodemon запускать сервер. Для этого добавим три строчки кода в файлик package.json:

Теперь запускать стало намного удобнее:

Скрипт запуска

Маршрутизация

Маршрутизация интуитивно понятна при использовании Hapi. Есть три основных управляющих компонента:

  • path – путь.
  • method – GET , POST или что-то другое.
  • handler – обработчик.

Внутри метода init мы добавили к серверу новый метод route с параметрами, переданными в качестве нашего аргумента.

Настройка базы данных

Как уже говорилось выше, мы будем использовать MongoDB вместе с mongoose. Последний добавляется одной командой:

+ строкой в файле:

Чтобы не запускать Mongo на локальной машине, мы будем использовать облачное хранилище mlab. Выбор пал на это облако из-за возможности бесплатного использования и простоты настройки (вы можете выбрать другой сервис). Создаем базу и пользователя – это и вся настройка mlab.

Подключаем mongoose к mlab

Чтобы связать мощный API с mongoose и mlab, нужно в файл index.js добавить несколько строк с параметрами подключения:

Тут мы указали mongoose, к какой базе будем подключаться. Убедитесь, что вы используете правильные учетные данные. Можно попробовать запустить наш скрипт run, и если вы все правильно сделали, то в терминале появится сообщение: connected to database.

Хотите освежить свои знания по Mongo? Вот вам небольшой туториал:

Создание моделей

При работе с MongoDB нужно следовать правилам моделирования данных.

Моделирование данных

Мы просто объявляем свою схему для коллекций. Если говорить образно, то представляйте коллекции, как таблицы в базе данных SQL.

Давайте создадим директорию models, а внутри нее файл painting.js. Он будет хранить в себе все данные, относящиеся к картинам. Выглядеть такой файл будет следующим образом:

  • Мы подключаем в наш мощный API зависимости mongoose.
  • Объявляем нашу PaintingSchema, вызывая конструктор схемы mongoose и передавая параметры. Обратите внимание, как все жестко типизировано: поле name может содержать только строку, а technique – массив строк.
  • Экспортируем модель и называем ее Painting.

Попробуем извлечь все картины из базы. Для этого сначала нужно добавить строку в файл index.js:

Чтобы каждая картина имела свой id (api/v1/paintings/{id}), добавим методы GET и POST в секцию с маршрутами. GET будет получать все картины, а POST – добавлять новые.

  • Мы создали GET с путем /api/v1/paintings. Внутри обработчика мы вызываем схему mongoose. У него есть удобный метод – find(), который возвращает все картины, если ему ничего не передано в параметрах.
  • POST мы создали для того же пути. Остановимся подробнее на этом. Ранее в схеме мы определяли поля: name, url, techniques. Здесь мы просто принимаем аргументы из запроса и передаем их в схему mongoose. Потом вызывается метод save() и происходит сохранение.

Если перейти по ссылке

мы должны увидеть следующее:

paintings array

Наш мощный API вернул пустой результат, т. к. в базе пока нет картин, но мы это исправим.

Для создания коллекции с запросами к API мы будем использовать очень крутой инструмент – Postman. Устанавливаем его по инструкции, и после этого заходим на веб-морду этого сервиса:

postaman

  • Слева вы можете видеть опции метода. Выберите там POST.
  • Следующее поле – URL. Это адрес, на который будет отправлен наш метод.
  • Синяя кнопка справа отправляет запрос.
  • Под URL поле с опциями. Кликните по body и заполните поля, как в примере ниже.

Теперь еще раз откроем нашу ссылку:

Картины

Беремся за GraphQL

GraphQL помогает справиться с многими неприятными моментами, с которыми могут столкнуться традиционные API REST. Вот некоторые из них:

  • Over-fetching – в ответе есть данные, которые не используются.
  • Under-fetching  – получено недостаточно данных после выборки, что приводит к повторному запросу.

GraphQL стал настолько популярным отчасти потому, что у людей есть веские основания полагать, что он полностью заменит REST-так же, как REST заменил SOAP.

Устанавливаем:

Apollo – это связующее звено между нашим Hapi-сервером и GraphQL.

Далее создадим новую папку с названием graphql и положим в нее файл PaintingType.js с таким содержимым:

Теперь нам нужно создать файл schema.js в этой же папке. Наполним его следующим образом:

В конце мы экспортируем наш корневой запрос и передаем его на сервер hapi. Обратите внимание на тип GraphQLSchema – это определение корневого запроса/схемы, которое мы передаем серверу.

Следующим шагом подключим к проекту GraphQL через файл index.js двумя строчками:

Зарегистрируем плагин:

И зарегистрируем плагин вместе со схемой:

Последний штрих

Последний шаг – наделим наш мощный API созданием документации. Для этого будем использовать мощный инструмент Swagger, позволяющий в полной мере воспользоваться спецификацией OpenAPI.

Устанавливаем:

Регистрируем:

Страничка документации доступна по уже известному адресу:

Документация

Оригинал

Другие материалы по теме:

Интересуетесь веб-разработкой?

Подпишитесь на нашу рассылку, чтобы получать больше интересных материалов:

И не беспокойтесь, мы тоже не любим спам. Отписаться можно в любое время.




9 Комментарии

  1. У вас в начале «API GraphQL API на базе Node.js» а в первом листинге табуляция превратилась в »      » и еще мне буквально на секундочку показалось что я видел эту статью на медиум.ком…

  2. Скрипт не отражает написанного ниже — «Объявляем нашу PaintingSchema, вызывая конструктор схемы mongoose и передавая параметры. Обратите внимание, как все жестко типизировано: поле name может содержать только строку, а technique – массив строк.» — там нет массива строк

  3. «Ваш комментарий ожидает модерацию» — возможно я ошибаюсь но не будет-ли более «по русски» — Ваш комментарий ожидает модерациИ…

  4. Вот еще из статьи непонятно зачем мы туда добавили GraphQL… Что это дало, непонятно… И форматирование исходников потекло… А в целом мне было интересно читать, спасибо.

    • Добавили краткое описание того, почему этот инструмент был добавлен в проект.

Оставьте комментарий