Unlimited Plugins, WordPress themes, videos & courses! Unlimited asset downloads! From $16.50/m
Advertisement
  1. Code
  2. Node.js
Code

Дизайн RESTful API c NodeJS и Restify

by
Difficulty:IntermediateLength:LongLanguages:

Russian (Pусский) translation by Anton Lisovsky (you can also view the original English article)

Final product image
What You'll Be Creating

Restful API состоит из двух основных концепций: Ресурс (Resource) и Представление (Representation). Ресурс может представлять из себя любой объект ассоциированный с данными или определён в качестве URI (больше чем один URI может ссылаться на один и тот же ресурс) и управлять им можно используя HTTP методы. Представление - это способ, которым вы отображаете ресурс. В данном туториале мы разберём теоретическую информацию касательно дизайна RESTful API и реализуем пример API приложения - блога, используя NodeJS.

Ресурс

Выбор правильных ресурсов для RESTful API является важной частью дизайна. Для начала, вам следует определиться со сферой вашего бизнеса и решить как много и каких ресурсов будут использованы, требуются вашему бизнесу. В случае, если речь идёт о дизайне API блога, вы скорее всего будете использовать Article, User и Comment. Это были названия ресурсов, данные которые ассоциированы с этими названиями, сами по себе являются ресурсами:

Методы ресурса

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

Таким же способом, вы можете просмотреть существующую статью, выполнив следующий запрос:

Что насчёт обновления существующей статьи? Я могу слышать, как вы говорите:

Я могу сделать очередной POST запрос на /articles/update/123456789012.

Может быть и неплохой вариант, но URI станет более громоздким. Как мы упоминали ранее, действия могут представлять из себя HTTP методы. Это означает, лучше выбрать updte метод вместо того, чтобы использовать URI. К примеру:

Кстати в данном примере вы можете заметить поля тегов и категорий. Данные поля не обязательны. Вы можете оставить их пустыми и установить значение в будущем.

Иногда вам понадобится удалить статью если она устарела. В этом случае используйте DELETE HTTP запрос для /articles/123456789012.

Методы HTTP - стандартная концепция. Используя их в качестве действий, вы будете обладать не сложным URI, пользователи оценят подобное простое API.

Что если вам захочется добавить комментарий в статью? Выберите необходимую статью и добавьте новый комментарий. Для этого подойдёт следующий запрос:

Форма ресурса выше называется под-ресурсом (sub-recource). Комментарий (Comment) под-ресурс Статьи (Article). Комментарий выше будет добавлен в базу данных как потомок Статьи. Иногда различные URI ссылаются на один и тот же ресурс. К примеру, для просмотра комментария вы можете использовать:

или:

Версии

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

  1. Версия в URI: можно предоставить номер версии в URI. К примеру, /v1.1/articles/123456789012.
  2. Версия в хедере: URI остаётся без изменений, однако в хедере передаётся номер версии, к примеру:

Вообще версия меняет только представление ресурса, но не саму концепцию ресурса. Поэтому вам не нужно менять структуру URI. Предположим в v1.1 было добавлено новое поле для статьи. Однако возвращается всё также статья. Используя вторую опцию, URI остаётся простым и пользователю не приходится менять URI на стороне клиента.

Важно учесть случаи когда клиент не передаёт номер версии. Можно показать сообщение об ошибке или вернуть ответ используя первую версию. В том случае если по умолчанию используется последняя стабильная версия, пользователь в результате может получить огромное количество ошибок со стороны реализации на клиенте.

Представление

Представление - способ, которым API отображает ресурсы. Когда осуществляется обращение к API возвращается ресурс. Данный ресурс может быть каким угодно форматом, к примеру XML, JSON и так далее, JSON предпочтительнее, в случае если речь идёт о новом API. Однако, если обновляется существующее API, которое уже реализовано с XML форматом, можно предоставить другую версию с ответами формата JSON.

Достаточно теории о дизайне RESTful API. Давайте разберём пример из реальной жизни, разработаем дизайн и реализацию API блога с помощью Restify.

REST API блога

Дизайн

Для того чтобы создать дизайн RESTful API, нам нужно проанализировать сферу деятельности нашего приложения. Тем самым мы будем в состоянии определить необходимые ресурсы. Для API блога, нам нужно:

  • Возможность создавать, обновлять, удалять, просматривать статью (Article)
  • Создать комментарий для какой-либо статьи, обновить, удалить, просмотреть комментарий (Comment)
  • Создавать, обновлять, удалять, просматривать пользователя (User)

Для данного API я не буду рассматривать аутентификацию пользователя для создания статьи или комментария. Чтобы ознакомится с реализацией аутентификации взгляните на туториал Аутентификация основанная на токенах с AngularJS и NodeJS.

Названия ресурсов готовы. Действия совершаемые над ресурсами представляют обычный CRUD. Ознакомьтесь с таблицей ниже, чтобы иметь представление о нашем API.

Название ресурса HTTP действие HTTP методы
Article create Article
update Article
delete Article
view Article
POST /articles с данными
PUT /articles/123 c данными
DELETE /articles/123
GET /article/123
Comment create Comment
update Coment
delete Comment
view Comment
POST /articles/123/comments с данными
PUT /comments/123 с данными
DELETE /comments/123
GET /comments/123
User create User
update User
delete User
view User
POST /users с данными
PUT /users/123 с данными
DELETE /users/123
GET /users/123

Настройка проекта

В данном проекте мы будем использовать NodeJS с Restify. Ресурсы будут сохранятся в базе данных MongoDB. Для начала мы можем определить наши ресурсы, как Restify модели.

Статья

Комментарий

Пользователь

Для ресурса User не будет никаких действий. Предполагается, что нам уже известен текущий пользователь, который будет взаимодействовать со статьями.

Вы можете спросить откуда добавляется модуль mongoose. Это самый популярный ORM фреймворк для MongoDB - модуль написанный на NodeJS. Данный модуль добавляется в проект в другом файле с конфигурацией.

Теперь мы можем определить HTTP действия для ресурсов описанных выше. Можно заметить следующее:

В данном кусочке кода, сперва все файлы с контроллерами, которые содержат методы контроллера, обрабатываются и инициализируются для запуска запроса к URI. После этого, URI для действия определяют основные CRUD действия. Также для одного действия с Article доступны разные версии.

К примеру, если установлена версия 2 в хедере Accept-Version, будет выполнен viewArticle_v2. viewArticle и viewArticle_v2 оба делают тоже самое, показывают ресурс, но в разных форматах, как можно заметить в поле title. Наконец, сервер запущен на определённом порту, добавлена проверка ошибок. Мы можем продолжить работу с методами контроллера для HTTP действий ресурсов.

article.js

Вы можете найти подробности об основных CRUD действиях Mongoose ниже:

  • createArticle: простое сохранение (save) для articleModel посылаемое из тела запроса. Новая модель может быть создана передавая тело запроса, как конструктор для модели, такой как var articleModel = newArticle(req.body).
  • viewArticle: чтобы увидеть детали статьи, в качестве URL параметра нужен ID статьи. findOne с ID параметром, достаточно для получения деталей.
  • updateArtcle: обновление статьи обычный запрос поиска и манипуляция с данными возвращённой статьи. Наконец, необходимая, обновлённая модель должна быть сохранена в базе данных с помощью команды save.
  • deleteArticle: findByIdAndRemove - лучший способ удалить статьи согласно переданному ID.

Команды Mongoose упомянутые ранее - статичны, как объект Article, который также является ссылкой на схему Mongoose.

comment.js

Когда вы делаете запрос одного из URI ресурсов, соответствующая функция описанная в контроллере будет запущена. Каждая функция внутри файла контроллера может использовать req и res объекты. Ресурс comment является под-ресурсом Article. Все действия запроса осуществляются через model статьи, чтобы найти под-документ и сделать необходимые обновления. Однако, когда вы пытаетесь посмотреть ресурс комментария, вам удастся его увидеть, даже если в MongoDB нет коллекции.

Другие рекомендации по дизайну

  • Выбирайте легкий для понимания ресурс, тем самым вы облегчите процесс использования клиенту.
  • Пускай бизнес логика будет реализована клиентом. К примеру, ресурс статьи имеет поле slug. Клиенту не нужно отправлять данную информацию REST API. Всё что связанно со slug должно быть обработано на стороне REST API, чтобы уменьшить сопряжение (coupling) между API и клиентом. Клиенту нужно только посылать детали заголовка и вы можете создать slug согласно бизнес потребностям на стороне REST API.
  • Реализуйте уровень авторизации для конечных точек API. Неавторизированные клиенты могут получить доступ только к ограниченным данным, которые принадлежат другим пользователям. В данном туториале мы не рассмотрели ресурс User, но вы можете ознакомится с Аутентификация основанная на токенах с AngularJS и NodeJS для получения информации о API аутентификации.
  • User URI вместо строки запроса. /article/123 (хорошо), /articles?id=123 (плохо).
  • Не сохраняйте состояние; всегда используйте мгновенный ввод/вывод.
  • Используйте существительные для ресурсов. Можно использовать методы HTTP для взаимодействия с ресурсами.

Ну и наконец, если разрабатывать RESTful API и следовать данным правилам, у вас всегда будет гибкая, простая в поддержке и понимании система.

Advertisement
Advertisement
Advertisement
Advertisement
Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.