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

2017.02.13

こんにちは!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 ではリソースに直接ファイルを紐付ける方式を採用いたしました。

さいごに

KUFU では SmartHR API を共に拡充してくれる人材を大募集中です!
ご興味を持っていただけましたら、ぜひ以下のリンクよりご連絡くださいませ。

株式会社クフの採用/求人一覧 – Wantedly

また、次回の API Study が 2/21(火) に予定されています!
私と弊社 CTO の佐藤も参加予定ですので、もしご興味がありましたらご参加くださいませ。

APIStudy#5 - connpass

引き続き、SmartHR をよろしくお願いいたします。

芹澤雅人

なめろうとホッピー、そして API をこよなく愛するエンジニアです
他の執筆記事はこちら

メンバーを募集しています!

SmartHR を共に成長させてくれるメンバーを募集しています!
ご興味を持っていただけましたら以下のリンクよりご気軽にご連絡ください。

株式会社SmartHRの採用/求人一覧 – Wantedly

引き続き、SmartHR をよろしくお願いいたします。

新着記事

週間ランキング