Как создать RESTful API на Ruby

В настоящее время каждый крупный онлайн-сервис предлагает API. Сокращение для интерфейса прикладного программирования, он предоставляет разработчикам программный доступ к сервису. Существуют разные типы API, но большинство из них сводятся к RESTful, JSON API. Если вы планируете создать приложение, добавление API обязательно должно быть в вашей дорожной карте.

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

Что нам понадобится

Для этого урока вам понадобятся Ruby (желательно 2.6) и Ruby on Rails. Оба относительно просты в установке, но процедура зависит от платформы, на которой вы работаете. Чтобы установить Ruby, обратитесь к официальному сайту за инструкциями. Установить Rails тоже довольно просто: вы можете воспользоваться их официальным руководством по установке.

Кроме того, вам понадобится ваш любимый редактор кода. Лично я предпочитаю Visual Studio Code, но не стесняйтесь использовать тот редактор, который вам удобнее всего.

Все настраивается

Поскольку мы собираемся создавать API, нам совсем не нужно все, что предлагает Rails. Например, мы не будем отображать HTML-представления. К счастью, генератор приложений Rails предлагает возможность создать более «экономичную» версию приложения Rails, в которой установлены только необходимые модули для API. Его можно дополнительно настроить в зависимости от ваших потребностей. В нашем случае мы создадим новый проект API, а также пропустим ActiveRecord, поскольку нам не нужно будет ничего хранить в базе данных.

rails new cow_say --api --skip-active-record

После того, как эта команда будет выполнена, нам нужно будет добавить еще два драгоценных камня в наш Gemfile:

# Gemfile 
gem 'ruby_cowsay' 
gem 'jbuilder'

Первая жемчужина - это то, что позволит нам обслуживать Cowsay для наших клиентов API. Это рубиновая реализация известной программы. Гем jbuilder упрощает обслуживание JSON в нашем API, позволяя нам создавать полезные данные с использованием простого рубина. Убедитесь, что вы запустили bundle install, чтобы получить драгоценные камни.

Добавление контроллера и маршрута

На данный момент у нашего API будет только одна конечная точка: /say. Клиенты отправят на эту конечную точку POST с набором параметров и получат от нас ответ. Давайте добавим эту конечную точку в наш файл маршрутов:

# config/routes.rb
Rails.application.routes.draw do
  post 'say', to: 'cow#say'
end

Это означает, что отправьте сообщение POST в /say и направьте его методу say в CowController. Теперь нам нужно создать наш контроллер и метод:

# app/controllers/cow_controller.rb
class CowController < ApplicationController
  def say
    @message = Cow.new.say(params[:message])
  end
end

Здесь очень простой метод. На данный момент все, что мы делаем, - это создаем сообщение из параметров и присваиваем его переменной экземпляра @message. Позже мы добавим некоторые проверки и дополнительные параметры. Чтобы отобразить это и показать нашим клиентам API, нам нужно создать представление. Как и в обычном приложении Rails, ответы JSON отображаются с использованием представлений, но вместо использования ERB (встроенного Ruby) для генерации ответа HTML мы будем использовать Jbuilder для генерации ответа JSON:

# app/views/cow/say.json.jbuilder 
json.message @message

Наша точка зрения не требует большего, чем это. Документация JBuilder поможет вам, если вы здесь заблудились, но в основном это говорит ему создать корневое свойство с именем message в ответе JSON и присвоить ему переменную экземпляра @message. Jbuilder может предложить гораздо больше, чем просто чрезвычайно простой рендеринг, поэтому мы рекомендуем просмотреть их документацию.

Тестирование нашего API

Мы уже создали наш API! Чтобы проверить это, вы можете использовать Почтальон или Бессонницу. В этом руководстве мы будем полагаться только на завиток. Сначала загрузите сервер Rails:

rails server

Подождите, пока ваш сервер запустится, затем в другом терминале запустите команду curl, чтобы протестировать новую конечную точку:

curl localhost:3000/say \ 
  -H 'Content-Type: application/json' \
  -d '{"message": "Hello from RapidAPI"}' \

Эта команда отправляет полезную нагрузку JSON со строкой «Hello from RapidAPI» в нашу say конечную точку. Если все пойдет правильно, вы получите что-то вроде этого:

{"message":" _____________________ \n\u003c Hello from RapidAPI \u003e\n --------------------- \n \\ ^__^\n \\ (oo)\\_______\n (__)\\ )\\/\\\n ||----w |\n || ||\n"}

На самом деле это не так уж и много, но это только из-за форматирования. Мы можем использовать быстрый трюк с использованием ruby, чтобы проанализировать ответ JSON и распечатать результат. Запустите это:

curl localhost:3000/say \ 
  -H 'Content-Type: application/json' \ 
  -d '{"message": "Hello from RapidAPI"}' \ 
| ruby -r json -e "print JSON.parse(STDIN.read)['message']"

Здесь мы перенаправляем вывод нашей команды curl в ruby, где нам нужен модуль json и используем его для синтаксического анализа ответа, получения свойства и print его, что гарантирует правильность представления ответа. Теперь вы должны увидеть, как корова произносит ваше предложение:

Дополнительные параметры и проверка

Пока наш API простой. Возможно, слишком просто. Давайте поднимемся на ступеньку выше. Камень Cowsay, который мы используем, принимает множество параметров для настройки того, что он генерирует. Например, это не обязательно должна быть корова, которая что-то говорит, это может быть динозавр. Вы также можете превратить текстовый пузырек в мысленный пузырек. Более того, наша корова даже может выглядеть параноиком! Измените метод say в нашем контроллере коровы на этот:

# app/controllers/cow_controller.rb
class CowController < ApplicationController
  def say
    message      = params[:message]
    cow          = params[:cow] || 'cow'
    balloon_type = params[:balloon_type] || 'say'
    face_type    = params[:face_type] || 'default'
@message = Cow
      .new(cow: cow, face_type: face_type)
      .say(message, balloon_type)
  end
end

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

curl localhost:3000/say \
  -H 'Content-Type: application/json' \
  -d '{"message": "Hello from RapidAPI", "cow": "stegosaurus", "balloon_type": "think"}' \
| ruby -r json -e "print JSON.parse(STDIN.read)['message']"

У вас должен получиться симпатичный динозавр:

Пока мы занимаемся этим, давайте добавим некоторую проверку нашему API. Должны быть разрешены только некоторые параметры, а параметр message должен быть обязательным. Это легко сделать с помощью сильных параметров Rails:

# app/controllers/cow_controller.rb
class CowController < ApplicationController
  def say
    params.require(:message)
    params.permit(:cow, :balloon_type, :face_type)
message      = params[:message]
    cow          = params[:cow] || 'cow'
    balloon_type = params[:balloon_type] || 'say'
   face_type    = params[:face_type] || 'default'
@message = Cow
      .new(cow: cow, face_type: face_type)
      .say(message, balloon_type)
  end
end

Обратите внимание на выделенные строки. Здесь мы require, что параметр message присутствует, и мы разрешаем присутствовать только параметры cow, balloon_type и face_type. Остальные отбрасываются Rails. Теперь не стесняйтесь поэкспериментировать со своим API. Вы можете получить любую из этих коров в своих отзывах. Обратите внимание, что не все поддерживают разные типы лиц.

Как опубликовать свой API на RapidAPI

RapidAPI - это торговая площадка API-интерфейсов, которая упрощает их поиск. Также можно использовать разные API с помощью одного SDK, и оплата объединяется в одну учетную запись. Но сначала ваше приложение должно быть где-то размещено. Начнем с этого.

Развертывание на Heroku

Самый простой способ разместить этот API - Heroku. Если вы не знакомы с ними, они предлагают чрезвычайно удобный способ размещения проектов. Развертывание также простое. Просто запустите команду на своем терминале, а они сделают все остальное. Идите и зарегистрируйтесь, если вы еще не сделали этого. Затем вам нужно будет установить Heroku CLI. Установка зависит от вашей платформы, поэтому ознакомьтесь с различными вариантами здесь. После этого войдите в Heroku на своем терминале и следуйте инструкциям:

heroku login

После того, как вы закончите, запустите heroku create в том же каталоге, что и приложение Rails. Это создаст новое приложение на Heroku и предоставит вам домен. Он также настроит ваш проект Git (Rails автоматически создаст его для вас), чтобы вы могли развернуть его в Heroku, просто запустив git push. Поскольку Heroku полагается на Git и историю нашего репозитория, нам нужно зафиксировать наш прогресс. Если вы не знакомы с Git, просмотрите учебные ресурсы на GitHub.

git commit -a -m "Initial commit"

Теперь запустите git push heroku master на своем терминале. Это перенесет нашу основную ветку на Heroku и развернет наше приложение. Когда команда завершится, вы увидите что-то подобное:

remote: -----> Launching...
remote:        Released v4
remote:        https://nameless-river-12345.herokuapp.com/ deployed to Heroku

Теперь ваш API доступен на Heroku! Вы можете попробовать те же команды curl, которые мы пробовали раньше, просто замените http://localhost:3000 URL-адресом вашего приложения Heroku.

Опубликовать на RapidAPI

Теперь, когда ваш API подключен к сети, мы можем добавить его в RapidAPI. Перейдите в RapidAPI и нажмите Добавить свой API в правом верхнем углу. Введите имя и описание вашего API, а затем выберите категорию.

Сначала нам нужно настроить наш API. Нажмите «Настройки» вверху, затем установите «Базовый URL-адрес» на корневую конечную точку приложения Heroku (ту, которую вы получили только что). Далее нам нужно настроить некоторые преобразования. Внизу нажмите «+ Добавить секретный заголовок или параметр». В качестве имени установите значение Content-Type, а в качестве значения установите application/json. Теперь добавьте еще один заголовок, но на этот раз задайте имя Accept и значение application/json. Это заголовки, которые RapidAPI отправляет нашему API, поэтому он знает, как читать параметры, которые ему отправляют клиенты.

Снова вверху нажмите «Конечные точки», затем нажмите «+ Создать конечную точку». Здесь определите имя для конечной точки (например, что-то вроде «Say»), затем установите метод на POST и путь на /say. Ниже, рядом с «Полезной нагрузкой», нажмите «Добавить модель». Здесь вы можете просто указать имя (в этом случае достаточно «Payload») и образец тела. В нашем случае мы будем использовать это:

{"message": "Hello from RapidAPI", "cow": "stegosaurus", "balloon_type": "think"}

Теперь продолжайте и нажмите кнопку «Сохранить и протестировать конечную точку». Через несколько секунд вы должны получить ответ. Все готово!

Заключение

В этой статье вы узнали, как создать API с помощью Ruby on Rails. Вы также узнали, как развернуть его на Heroku и опубликовать на RapidAPI. Мы рекомендуем вам прочитать, как настроить базу данных на Heroku, чтобы вы могли добавить эту возможность в свои API. Также ознакомьтесь с документацией RapidAPI по публикации API-интерфейсов, чтобы лучше понять все варианты.

Статьи по Теме

Первоначально опубликовано на https://blog.rapidapi.com 24 сентября 2019 г.