🍎

Railsを使ったAPI連携について（例：smartHR）！

2024/06/02に公開

Rails

そもそも外部API連携とは？

まず、外部API連携について説明します。
外部API連携とは、自社サービスなどに外部の便利なサービスを取り入れるための手段です。
例えば、Railsで自社サービスを作成している時にそのサービスの中にchatGPTのような機能を実装したいと考えたとします。こんな時に、０からchatGPTを作成するのはほぼ不可能です。ですが、APIという便利な技術を使用すれば、chatGPTの一部の機能を自社サービスに取り入れることができます。
このようなことを可能にするのが外部API連携です。

ex. YouTubeとのAPI連携、GoogleMapとのAPI連携、smartHRとのAPI連携など、、、

chatGPTとRailsのAPI連携は下記の記事が非常にわかりやすかったので載せておきます。

APIの仕組み

ここでは、APIが便利なのはわかったけど、どんな仕組み動いているのかについて説明します。
大まかに、API連携の仕組みは二つです。それは、自社サービスから欲しい情報について「リクエスト(要求)」を送ることと連携したいAPIからリクエストに対しての「レスポンス（返答）」をもらうことです。

下記の画像が非常にわかりやすかったので載せておきます。

引用元：https://www.sbbit.jp/article/image/111892/bit202304141527337876.jpg

Railsで外部API連携をする手順

APIの仕組みについて、簡単に理解したところで次は実際にRailsでどうやってAPI連携を実装するのかについて説明していきます。もちろん、API連携するサービスによって多少違いがあるかもしれませんが大きくは以下の手順が基本になります。

①API連携用のライブラリを導入（Rails側）
②API Keyの取得（APIとして利用するサービス側）
③Railsのコントローラなどでリクエスト(要求)を送る処理の実装（Rails側）
④レスポンスをRailsで処理できる形に整形（Rails側）

順に見ていきます。

①API連携用のライブラリを導入（Rails側）

まず、API連携をするためにリクエストを送ったり、レスポンスを受け取ったりしなければいけないのですがこの仕組みを０から実装するのは面倒なのでライブラリを使用します。

RailsでAPI連携を考えた時によく出てくるライブラリは以下の二つです。

Gemfile

#拡張性が高い
gem 'faraday'
#シンプルでわかりやすい
gem 'httparty'

Railsには他にもたくさんのライブラリが準備されていますので、用途に合ったライブラリをインストール(bundle install)しましょう。今回は、'faraday'を例に説明をしていきます。

②API Keyの取得（APIとして利用するサービス側）

この項目が、利用したいAPIによってAPIKey取得の方法が若干異なるところなので仕様を調べながら行う必要があります。
今回は、smartHRというサービスを例に説明していきます（会社で使ってるという方もいるかなと思い、、、）。

API Keyの取得については、下記の公式ドキュメントが非常にわかりやすかったので、説明は省いてここでは、なぜAPI Keyなるものが必要なのかについて説明します。

結論から言うと、セキュリティ上の問題でリクエストできるユーザーを制限するためです。
例えば、今回の例であるsmartHRなどでは、会社の従業員の情報などをレスポンスとして受け取ることができるようになります。このような情報は誰でも見れていいわけがありません。
せいぜいその会社の従業員、もしくはその権限を持った従業員だけがアクセスできなければいけません。
そこで必要になるのが、API Keyです。
Rails側では、ここで取得したAPI Keyをリクエストと同時に送信します。
これに対して、smartHR側ではAPI Keyの認証をした後、認証をクリアした場合のみレスポンスを返すようになります。これによって、APIにアクセスできるユーザーを制限することができます。

③Railsのコントローラなどでリクエスト(要求)を送る処理の実装（Rails側）

今回は、smartHRとのAPI連携のためのモジュールとそれを使用するコントローラのコードを記述します。エンドポイントやAPI Keyなどは適宜、ご自身の環境のものに変更して使ってみてください。

smarthr.rb

require 'faraday'

module SmartHR
　# SmartHRのAPIのベースURLを指定（エンドポイント）
  API_URL = '〇〇'  

  class Client
    # API Keyの設定
    def initialize(api_key)
      @api_key = api_key
    end

    # API Keyとエンドポイントを使ってsmartHR側とのコネクションの設定
    def connection
      @connection ||= Faraday.new(url: API_URL) do |faraday|
        faraday.request :url_encoded
        faraday.headers['Authorization'] = "Bearer #{@api_key}"
        # 受け取るデータの形式を設定(jsonで受け取る)
        faraday.headers['Accept'] = 'application/json'
        faraday.adapter Faraday.default_adapter
      end
    end

    # getリクエストメソッド
    def get(endpoint)
      response = connection.get(endpoint)
      JSON.parse(response.body)
    end

    # postリクエストメソッド
    def post(endpoint, params = {})
      response = connection.post(endpoint, params.to_json, 'Content-Type' => 'application/json')
      JSON.parse(response.body)
    end

    # 必要に応じて、他のHTTPメソッドも追加してください
  end
end

〇〇コントローラ

def import
    # 環境変数に設定したSMART_HR_API_KEYを元にAPI Keyの設定
    smarthr_client = SmartHR::Client.new(ENV['SMART_HR_API_KEY'])
    # 先ほど作成したgetメソッドを使って、実際にsmartHRにリクエストを送信！！
    response = smarthr_client.get('リクエストを送りたいURLを指定')
end

④レスポンスをRailsで処理できる形に整形（Rails側）

ここでは、先ほどリクエストを送って帰ってきたresponseを元にRailsで使用できるような形に整形をしていきます。smarthr.rbのconnectionメソッド内にレスポンスをjsonにするという記述があると思うので、〇〇コントローラのresponse変数にはjson形式のデータが取得できています。

リクエストが従業員の情報などだったら、responseには以下のようなデータが格納されているはずです。

json

[
  {
    "id": "1",
    "name": "John Doe",
    "email": "john.doe@example.com",
    "position": "Software Engineer",
    "department": "Engineering",
    "start_date": "2020-01-15"
  },
  {
    "id": "2",
    "name": "Jane Smith",
    "email": "jane.smith@example.com",
    "position": "Product Manager",
    "department": "Product",
    "start_date": "2019-03-22"
  }
]

このようなjson形式のデータがresponseに格納されているのでresponse[id]のようにアクセスして、Railsのモデルに格納したり、整形したりして活用してみてください！