API Study に「RESTful API におけるファイルアップロード」というテーマで登壇しました！

こんにちは！SmartHR 開発チームの芹澤です。

先日 API Study #4 という勉強会に参加し、API に関する LT をさせていただきました。テーマは「RESTful な API におけるファイルアップロード」で、SmartHR API でファイルアップロード機能を実装するにあたって調査した内容をまとめたものになります。

今回はその設計思想について、改めてご紹介させていただきます。なお、LT の資料はコチラから、勉強会のレポートはコチラからご確認いただけますので、よろしければ併せてご覧くださいませ。

ファイルアップロードの仕様

SmartHR API ではリソースのファイル属性の項目に対して、以下のような JSON を構築して送信することでファイルのアップロードを行います。

{
  ...
  "awesome_file_attribute": {
    "file_name": "awesome_data.pdf",
    "content": "iouMjY6PkJGTlJWWl5iZmpucn..."
  }
  ...
}

ポイントとしては、

データを Base64 エンコードした文字列で送る
リソースに直接ファイルを紐付ける

の2点が挙げられます。では、それぞれについて詳しく見ていきましょう。

Base64 エンコードを採用した理由

HTTP を用いたファイル送信方式には multipart/form-data という RFC2388 で定義されたものがあります。これは、リクエストボディを「バウンダリ文字列」でいくつかのパートに区切ってデータを送信するというものです。王道な手法ではあるのですが、リクエストボディがピュアな JSON でなくなってしまうという制約があります。 SmartHR API では Input/Output 共に JSON フォーマットを採用していて、「Input で送信したものがほぼそのまま Output で返ってくること」を理想としています。なので、multipart/form-data は採用せず、JSON に埋め込める Base64 エンコード方式を採用いたしました。

リソースに直接紐付ける理由

SmartHR の性質的上、ファイルはリソース単位で所有されることがほとんどです。汎用的なアップローダを作る構想もあったのですが、リソースを横断して利用するファイルがない以上オーバースペックだと判断しました。また、アップローダの仕組みを使うと「ファイルアップロード」と「リソース紐付け」で2回のリクエストが必要になり、利用が少し煩雑になってしまうというデメリットもあります。以上の理由により、SmartHR API ではリソースに直接ファイルを紐付ける方式を採用いたしました。