- APIとは
- Web APIとは
- Web APIの具体例(サービスとして公開されたもの)
- Web APIの具体例(クローズドなもの)
- Web APIの理想の一つにRESTful APIがあるが
- 結果的になんちゃってRESTful APIとなる
- 処理手順について
APIとは
APIをざっくり説明すると、OSやアプリ等のシステムの機能を、他のアプリケーションでも利用できるようにした仕組みです。
これにより開発言語が異なっても、APIを使用するプラグイン等が用意されてれば、比較的容易にそれを利用できるようになります。
Web APIとは
Web APIについては、前項の「ご使用のOS等のシステムの機能」を「そのサイトのサービスで表示している情報」に置き換えたものだと思ってください。
さらに、アクセスはWeb＝HTML同様、HTTPプロトコルにて行います。
違いは、取得できるコンテンツが、デザイン装飾の付いたHTMLではなく、XMLやJSONという、データとして直に利用可能なフォーマットで受け取れることです。
Web APIの具体例(サービスとして公開されたもの)
一般的にはこのようなサービスです。
- 天気・気温や、株価や為替レートといった情報を取得するサービス
- Amazonや楽天のように、商品の値段やタイトルなどを取得できるサービス
- SelesforceやSlack、Twitterといった、外部サービスやSNSは手作業で入力するが、これを自動化するサービス
- Googleドライブやboxは手動でアップロードするが、これを自動化するサービス
公開するといっても、悪意のある第三者からのデータの改ざんを防ぐため、ユーザー登録に加え、アプリケーション登録を行い、トークンを取得して、そのトークンにてアクセスすることが主流となっています。
Web APIの具体例(クローズドなもの)
公開されてはいないものは、例えば、社内のイントラネットサービスです。
申請・承認といったワークフローシステムや、費用精算や、勤怠管理、自前のナレッジサイト、他社とのBtoBなどです。
Ruby on RailsやJava系のフレームワークなどのサーバーサイドスクリプトで開発すれば、DBはほぼ直接SQLで、あるいは言語特有の関数・メソッド群(ActiveRecordなど)を利用してアクセスすると思います。
この場合は、(公開されたAPIを利用する以外)APIのお世話になる行ことは、まずないでしょう。
ただ、以下のような開発環境(開発状況)では、ターゲットとなるDBにアクセスができません。
他にもあるかもしれませんが、私の経験したものは、この2つのケースです。
このように、クローズドなシステムでのWeb APIの活用は、クライアントの言語でのデータ取得の不備・不可能を補完するために活用されます。
100％ピュアなクライアントサイドスクリプトでの開発
100％ピュアなクライアントサイドスクリプトでの開発、例えばJavascriptのみでのシステム開発では、SQLを直接発行できません。
その場合は、以下のように解決します。
- クライアントサイドスクリプトではSQLを発行できない
- 代わりにDBアクセス用のWebサーバーを別途立ち上げ、そちらにAPIプログラムを作成する
- 欲しい情報✕更新・照会の数だけプログラムを用意する
- APIプログラムは、サーバーサイドからのパラメータをもとに、照会・更新を行い、その結果をJSONで返す
- クライアントサイドスクリプトはAJAXの技術を用いてAPIにアクセスし、結果、受け取ったJSONをもとに適切な処理を続行する
特定のDBシステムのアクセスが不可能なケース
「特定のDBシステムのアクセスが不可能なケース」とは、どのようなケースがあるでしょうか？
以下は私が経験したケースです。
- BtoB系(あるいはEC)パッケージを導入
- そのパッケージは、在庫管理や流通用の基幹システムに接続する必要があるが、その言語ではアクセス不可能
- 基幹システムとSQLでやり取りできる他の言語にて、別途APIサーバーを作成し、そこにアクセスし、データの照会・更新を行うこととした
私が何度か経験したものとしては、DBシステムとSQLでやり取りする際にはJDBCを利用するしかないといった場合、Web言語側がJDBCをサポートしていないために、そのDBとやり取りするために、JDBCが利用できる別の言語でAPIサーバーを立ち上げるといったケースです。
ならば、最初からJDBCが利用できるWeb言語のほうが良いかというと、そうでもないことのほうが多いです。
Web APIの理想の一つにRESTful APIがあるが
Web APIの理想の一つにRESTful APIがあります。
が、理想を追い求めると、こういったAPIを作ることになるでしょう。
- 処理の違いはMETHODで表現(GET/POST/PUT/PATCH/DELETE)
- URLに動詞を含めない
- URLに拡張子は含めない
- ユーニークなキーとなるidは、URLに含める
- POSTの場合のパラメータはフォームデータではなく、BODYにJSONを埋め込む
- データが存在しない場合は404、データ追加は201、更新や削除は204…と使い分ける
ですが、以下の点で不可能あるいはおすすめできません。
- PUT/PATCH/DELETEが未サポートあるいはデフォルトではない
- 上記の制限により「URLに動詞を含めない」ルールが実現できない
- 「URLに拡張子は含めない」が実現できない言語・フレームワークもある
- ユーニークなキーとなるidをURLに含めることができない言語・フレームワークもある
- 「POSTの場合もパラメータはJSONで」では添付ファイルが送れない
- 「データが存在しない場合は404、データ追加は201、更新や削除は204…と使い分ける」だと、つくり手が混乱する
以降に、問題点の詳細と解決策を提示します。
「PUT/PATCH/DELETE」が無理ならば
IISでは、確かデフォルトではNGだったと思います。
また、PUT/PATCH/DELETEはブラウザでは未サポートです。
(裏技的なやり方はあるようですが…)
ですので、開発時のわずらわしさから、GET/POSTのみで対応するようにしています。
「URLに動詞を含めない」が無理ならば
上記のようにGET/POSTのみにすると、私の経験では、このような状況になります。
- GETの場合は照会・削除、あるいはトグルのON/OFF
- POSTは登録あるいは変更
この場合は、動詞はURL上に含めたほうが良いかなと。
- get_xxxx
- delete_xxxx(あるいはcancel_xxxx)
- toggle_xxxx
- set_xxxx
上記のようなプログラム名でAPIプログラムを作成することが多いです。
「URLに拡張子は含めない」が無理ならば
素のphpやColdfusionでは拡張子が出てくるので、それは仕方ないかなと。
これは、API云々ではなく、URLアドレスを別途定義できるか、フォルダ構成をそのままURLにするかといった、Web言語(あるいはフレームワーク)の仕組みの違いかと思います。
「ユーニークなキーとなるidは、URLに含める」が無理ならば
こちらも、フォルダ階層がそのままURLになるようなタイプのWeb言語では、(可変値になるようなフォルダ構成は)実現できません。
パラメータはすべて、通常のGETパラメータで統一します。
(POSTの場合は、hidden値にします。)
「POSTの場合もパラメータはJSONで」が無理ならば
実際の開発では、添付ファイルを受け取るケースが多々あります。
この添付ファイルは、電子帳簿保存法施行により、レシートを添付し、DBの日付カラムでタイムスタンプの機能を代用したいといったニーズが、更に増えてくると思います。
このケースではフォームデータ(multipart/form-data)にするしか無いのですが、こちらのPOSTはフォームデータ、あちらはJSON…ではメンテナンス性に欠けてしまいますので、私はフォームデータに統一しています。
「データが存在しない場合は404、成功時も201・204と使い分ける」が無理ならば
404はURLが見つかりませんでも使われます。Webアプリケーションが不調な場合もWebサーバーが404を返すような場合、システム的に混乱を招くため、これは却下しました。
20xのバリエーション(201・204)も混乱するので200に統一。
結果的に、私がAPIを作成する場合は、このようにさせてもらっています。
- 追加・更新・削除に関わらず、正常終了は常に200で返す、URLミスは404、APIシステム自体のバグによるエラーは500で返す
- システム的に可能であれば、404や500でもJSONで渡せるようにする
- Data Not Foundは、404ではなく「”record_count” : 0」で判断してもらう
(あるいはデータの有無のフラグ値を渡す。) - 入力値エラー、更新エラーも200とした上で、JSONで表現し、具体的なエラー内容(メッセージテキスト)も返す
結果的になんちゃってRESTful APIとなる
まあ、それで良いと思います。
私は、ほとんど「無理」なWeb言語・フレームワークでAPIを作成することのほうが多い気がします。
できる限り、素早く割り切って、お互いに作りやすいシステムを作成することが大切ですね。
処理手順について
処理手順については、下記のコラムを参照してください。
さらに、実践的な記事も用意しています。
それでは、また。
