2章エンドポイントの設計とリクエストの形式
本章からいよいよ具体的なAPI設計のルールや方法について見ていくことにします。Web APIを公開するにあたっては、まずは何をAPIとして公開するのか、そしてどういったAPIとして公開するのかを考えなければなりません。まずはそのための公開する機能の決定と公開するエンドポイントの決め方、およびエンドポイントの設計について考えてみることにします。
2.1 APIとして公開する機能を設計する
APIを公開するにあたってはまず、APIとして何を公開するのかを決めなければなりません。そこでここではあなたがごく簡単なSNSサービスを作っていると仮定して、実際にどんなAPIを作るべきかを考えてみましょう。あなたが開発しているSNSサービスは表2-1のような機能があり、ウェブ、あるいはモバイル向けのクライアントアプリケーションを経由して操作することができます。あなたは公開するAPIを自分で開発を行うモバイルアプリケーションからのアクセスだけでなく、広く一般に公開してユーザーが利用できるものとしたいと考えています。
表2-1 SNSサービスの機能
| 機能 |
|---|
| ユーザー登録、編集 |
| 友達の検索、追加、削除 |
| 友達の間でのメッセージのやりとり |
では、この場合どういうAPIを用意すればよいでしょうか。
非常にシンプルにAPIを設計する方法として、サービスが利用するデータベースのテーブルを直接操作するようなものを作ることもできます。たとえばこのSNSサービスの場合は、ユーザー、友達のソーシャルグラフ情報、タイムラインの3つのテーブルが存在していると思われるので、それらをそれぞれ検索、編集できるようにすれば、サービスの操作は一応できてしまいます。
しかしそんなSQL文をただ包んだだけの設計では決して使いやすいAPIにはなりません。なぜならそんなAPIでは、データが内部的にどのように格納されているか、どういうリレーションを持っているかなどを理解していないと使うことができませんし、そもそもそんな内部構造を公開してしまうことはセキュリティを考えても大変危険なことだからです。したがってAPIはもう少し高い次元での機能を表すものである必要があります。 ...