[イプリオの事例紹介] Web API 開発・構築案件
こんにちは。イプリオのエンジニア背番号51です。
今回の事例紹介として、ある独立行政法人様での API 構築についてお話します。
あ、これあまり知られてないかもしれませんが、イプリオではネットワークやサーバに限らず開発の案件も頂いております！
[ 概要 ]
とある専門分野のユーザーが各種資料やメタデータなどを登録できるシステムで、以前に別の改修をお手伝いしたこともあり今回新たに API 構築のお話を頂きました。（API にも色々ありますが、ここで言う API は Web API を指します。）
API（Application Programming Interface）
皆さんは API、使っていますか？
開発者なら一度は利用したり作ったりしたことがあるかと思います。
同じシステム内に限らず、昨今では他のシステムやサイトと連携するパターン、よくありますよね。API 経由でデータを連携してサービスを提供するのはもう日常茶飯事なので、開発者でなくても、API をよく知らなくても、ブラウザからは実体がよく見えなくても、実は常日頃 API のお世話になっているのです。
Web API
Web API と言っても形式は一つではなく、ひと昔前なら SOAP（Simple Object Access Protocol）が主に使われていました。HTTP と XML で通信可能ですし、構造が複雑なデータをスキーマ定義してデータの入出力チェックも可能です。
一方、現在広く普及しているのが REST（REpresentational State Transfer） です。こちらは HTTP と JSON または XML を使って、エンドポイントに対し GET、POST、PUT、PATCH、DELETE メソッドでリクエストを送信します。XML だけでなく JSON で高速にデータをやり取りできたり、ブラウザからササッとアクセスできたり、curl で容易にリクエスト送信もできたりと柔軟な使い方ができるため Web API と言えば今では REST が多くを占めているようです。
今回対象としているシステムではもちろん GUI から登録や更新はできるのですが、
件数が多い際にフォームから一つ一つ作業をする手間を省略化したい
データをまとめた zip 形式のファイルから登録できるようにしたい
既に登録予定のデータが大量に蓄積されている
といった背景があり CLI から一括で登録できる API の構築となりました。
[ ポイント ]
開発期間は2か月強
既存のシステム上に構築
GitHub のリポジトリを使用してお客様と共同開発
認証機能は必須
決められた構成の zip ファイルを添付して API に送信
添付された zip ファイルを展開してデータ登録
処理結果をユーザーのメールアドレスに送信
[ アプローチ ]
API 設計
今回は、登録予定のデータが大量にあること、また、API で操作可能とすることにより GUI を経由せずとも CLI を使って zip ファイルからリソースの追加・更新を一括で行えるようにすることが目的です。
機能・要件の確認
当然ですが全てはここからですね。
エンドポイントの設計
機能・要件が決まったら、アクセス先であるエンドポイントの設計です。
いかにわかりやすく、統一感があり、且つ短く入力しやすいURIにするかを考慮しつつ、リソース操作の目的に応じて使用するメソッドも併せてURI毎に決定します。
認証形式
ユーザー認証が必要なシステムの場合、何を使って認証を行うのかによってリクエストの内容が異なります。Basic 認証やAPI キー認証など、認証形式にも色々あるので何を採用してどんな仕様にするかを決定します。
リクエストパラメータ
パスで渡すのかクエリで渡すのか、JSON(またはXML) のデータ構造や必要なパラメータ、入力チェックの仕様などなど。
レスポンスデータ
レスポンスの形式（JSON/XML）やステータスコード、内容、構造など、何をどう返すかの仕様を決めます。
エラーレスポンス
リクエストを受けてからレスポンスを返すまでの間に発生し得る全てのエラーに対し、ステータスコードやエラーメッセージ、処理内容を決定します。
トークン認証
正規ユーザーとして認証できることが必要なため、まずは認証機能を構築します。
今回は JWT(JSON Web Token) を使って認証する方針なので、パスワードでの認証が通ったら利用者を識別する情報や有効期限を設定したトークンをレスポンスとして返します。
利用者は発行されたトークンを使って有効期限内にその後のリクエストを行うことにより、リソースの操作が可能となります。
トークンは新規に発行するだけではなく、再発行・無効化もできる状態にしておきます。
zip で送って
認証が済んだら、資料やメタデータを丸ごと一つの zip ファイルとして添付して API に送り、リソースの登録/更新処理を行います。
いつもはダブルクリックすればOSやツールがよしなに解凍してくれる zip ファイルを、今回はシステム上で解凍し、中身を確認して問題無ければデータとファイルを追加していきます。
がしかし。
ご存じかと思いますが一言で zip と言っても色々なパターンがあるのです。
OS が余計なファイルを含めてくる
パスワードがかかってる
ファイル名の文字コードがバラバラ
zip のフリして zip じゃない
などなど、お客様と確認しながら zip ファイル自体に対するあらゆるケースを前提としたテストが必要でした。社内の協力もあって色々なパターンの zip ファイルを集めて検証し、それら全てを正常に処理可能とすることができました。
ファイル登録
無事解凍された zip には、
資料のドキュメントファイル
資料の著者名やタイトル、説明、カテゴリ、キーワードなどのデータが所定の形式で記載されたメタデータファイル
が含まれています。
データ形式やファイルサイズ、ファイル数、メタデータの項目チェックなどをクリアしたら登録処理を行い、何かしらの不備不足があればエラーを返し、登録完了となれば成功レスポンスを返して正常終了です。
ドキュメントもメタデータも、様々なケースで検証を行いました。
必須項目の欠損、書式が無効、ユニーク値であるところが重複、など数々の種類でテストデータを準備して、何種類もある zip 形式で圧縮したらそれぞれ API に投げていきます。
もともと膨大だったメタデータ項目に更新が入ることもありましたが、お客様からの迅速なアップデートの御蔭で滞り無く作業を進めることができました。
[ 成果 ]
いよいよ実稼働
ダミーデータでのテスト期間を経て検収も終わり、無事納品となりました。
その後実際のデータを API 経由で本番システムに一括登録した結果、大量の登録でも全て問題無く処理できたとの連絡を頂きました。バッチで処理できるようになったので、担当の方の負担も減ったとのこと。
当初の予定よりも早く、トラブル無く案件の終了を迎えることができたこと、今回もお手伝いできたことを大変嬉しく思っています。
[ 担当者として ]
効率化や自動化の処理に、今や API の利用は欠かせないものとなっています。
今回はクローズドな環境に向けた構築でしたが、別システムとの連携や複雑な認証も絡んでくる API では規模も大きくなりますし、設計による影響範囲も広くなります。既存 API を拡張する場合も同じです。
広く使われるようになったからこそ API の脆弱性やセキュリティーホールを突いた攻撃も近年急増しているので、セキュリティ対策を踏まえた設計・構築の重要性が高まっています。
そんな中、ユーザーとシステム、システム間の連携など、安全に「つなげる」ことでこれからもお客様をサポートしていけたら嬉しい限りです。
[ お問い合わせ ]
開発案件に関するお問い合わせは「イプリオのお問い合せページ」より、お気軽にご相談ください。
株式会社イプリオのエンジニアズです！ ネットワークやサーバに関わること。お客さまのインターネットでのビジネスを支えるコラムを連載していきます！