WebAPIの設計について #API

概要

以下の書籍で学んだことをまとめて、書いていきたいと思います。
Web API The Good Parts

Web APIとは何か

　本書で言うところのWeb APIとは、HTTPプロトコルを利用してネットワーク越しに呼び出すAPIです。簡単にいえば、あるURIにアクセスすることで、サーバ側の情報を書き換えたり、サーバ側に置かれた情報を取得したりすることができます。
Web APIの重要性として、近年は、APIの存在が企業やサービスの価値や収益を左右するケースが非常に多くなっています。例えば、Twitterは、Web APIを使用して、サービスを大きくした一例です。Twitterは、シンプルなアプリケーションなので、ほとんどの機能をAPIで行うことができました。なので、様々な周辺サービスが開発され、それにより、Twitterはどんどん集まる場所なっていきました。

何を公開すべきか

APIで公開するべきことは、そのサービスのコアの部分を公開すべきと書いてあります。
例えば、ECサイトであれば、商品の購入や検索、おすすめ情報の取得などそのサービスが価値を生み出している部分になります。

APIを公開することで得られるもの

　APIを公開することで、サービスの付加価値を他の企業や、個人が提供してくれることになり、サービスの価値や情報の質が上がることが考えられます。
例えば、ECサイトのAPIを公開すれば、ECサイトと繋ぎ込んで、自動で家計簿をつけてくれるサービスなども生まれたり、毎月の収支から何らかのアドバイスをしてくれるサービスができてくるかもしれません。

Web APIを美しく設計する重要性

Web APIを美しく設計した方が良い理由は、大きく以下の4つです。
・設計の美しいAPIは使いやすくなる。
・設計の美しいAPIは変更しやすい。
・設計の美しいAPIは頑強である。
・設計の美しいAPIは恥ずかしくない。
一つずつ説明します。

設計の美しいAPIは使いやすくなる。

作成したAPIを使うのは、基本的には自分では無いケースが多いです。なので、使いづらいAPIは開発時のストレスにもなりますし、開発にかかる時間にも影響するので、できるだけ簡単に使えるようにします。

設計の美しいAPIは変更しやすい。

システムやWebサービスはどんどん進化していくものなので、それぞれのサービスも変化していくものです。なのでそのインターフェイスのAPIも変化を余儀なくされます。なので、仕様変更した時に、APIも使用できなくなり、サービスも動かなくなってしまうのは、APIの提供者して避けたい事態なので、美しく設計することで、APIの変化をいかに利用者に影響なく行うかと言うことも含まれています。

設計の美しいAPIは頑強である。

Web APIはインターネットを通じて、サービスを提供するものです。なので、セキュリティの問題がつきまといます。APIといえど、HTTPを使用したWEBサービスになるので、ほぼ同じセキュリティ問題がありますが、API特有の問題も存在するので、そうした問題を考慮したAPIが美しいといえる。

設計の美しいAPIは恥ずかしくない。

Web APIを使用するのは、主に開発者が使用するものです。センスの疑われるAPIを公開してしまうと、公開した企業の技術レベルも疑われてしまいます。良いエンジニアは、技術力に無い会社やチームに参加したいとは思わないので、優秀な人材が他の会社に流出してしまうなどの事態に繋がってしまう可能性もあります。

Web APIを美しくするには

この本で書かれている思想の根幹をなす原則は以下の2つです。
・仕様が決まっているものに関しては仕様に従う。
・仕様が存在していないものに関してはデファクトスタンダードに従う。
一番大きな理由としては、開発者が他のAPIを使用していた場合、他のAPIで使われていた仕様と似たような仕様で設計されていれば、開発にかかる手間やストレスを軽減することにつながります。

エンドポイントの基本的な設計

URIの設計で一番重要な原則は以下のようなもの

覚えやすく、どんな機能を持つURIなのかが一目でわかる。

ということです。細かく書くと以下のような内容です。
・短くて入力しやすい
・人間が読んで理解できる
・大文字小文字が混在していない
・改造しやすい
・サーバー側のアーキテクチャが反映されない
・ルールが統括されている
1つずつ見ていきます。

短くて入力しやすい

https://api.example.com/service/api/search

これだと、URIの意味はわかりますが、少し冗長です。
このような場合は、以下のようにした方が良いとあります。

https://api.example.com/search

このようにした方がURIがシンプルになります。しかも、どちらも何かを検索するAPIであるという事は読み取れるので、このようにした方が良いです。

人間が読んで理解できる

これはつまりURIを省略したりせず、人間が理解できる英単語を使用するという事です。
以下のURIは省略したURIです。

https://api.example.com/sv/u

「api」とあるのでAPIのURIであることはわかりますが、「sv」と「u」という文字だけでは、どんな働きをするURIであるのかがわかりません。
次に、以下のURIです。

https://api.example.com/products/12345
https://api.example.com/productos/12345
https://api.example.com/seihin/12345

1つ目は英語、2つ目はスペイン語、3つ目は日本語です。
スペイン語は英語に似ててわかりにくいですし、日本語は理解できる人も少ないので適していません。
英語でも、同じような意味でも様々な単語があるので、わからない場合は、他の同じような働きをしているAPIで、どのようなAPIが使われているのかを調べてみるのが良いです。

大文字と小文字が混在していない

URIは基本的には小文字を使う。大文字を使うのであれば統一する。

http://api.example.com/Users/12345
http://example.com/API/getUserName

このように大文字小文字が混在しているとAPIをわかりづらく、間違えやすくします。したがって、以下のように、どちらかに統一して、標準的には小文字を使用する。

http://api.example.com/users/12345

このようにする。

改造しやすい

例えば、以下のようなエンドポイントがあったとします。|

//IDの範囲 1~300000
//エンドポイント http://api.example.com/v1/items/alpha/:id
//IDの範囲 400001~500000
//エンドポイント http://api.example.com/v1/items/beta/:id

このようにすると、アイテムの数(ID)の数が増えていくにつれて、エンドポイントも考えていかなければなりません。なので、改造がしにくいURIになってしまいます。

サーバー側のアーキテクチャが反映されない

例えば、以下のようなエンドポイントがあったとします。

http://api.example.com/cgi-bin/get_user.php?user=100

これだと、このAPIはPHPで書かれたものだとわかってしまいます。こうした情報は利用者には全く必要ありませんし、サーバの脆弱性にもつながってしまいます。

ルールが統括されている

以下のURIを例とします。
○友達の情報の取得

http://api.example.com/friends?id=100

○メッセージの投稿

http://api.example.com/friend/100/message

この二つのURIが同じサービスで使われているURIだとしたら、あまり良くないAPIになってしまいます。なぜなら、利用者からしたら統一性がないので、使いにくいですし、トラブルの原因となってしまいます。
以下のようにすると良いでしょう。

○友達情報の取得

http://api.example.com/friend/100

○メッセージの投稿

http://api.example.com/friend/100/message

HTTPメソッドとエンドポイント

メソッドの例は以下の通りです。

メソッド名	説明
GET	リソースの取得
POST	リソースの新規取得
PUT	既存リソースの更新
DELETE	リソースの削除
PATCH	リソースの一部更新
HEAD	リソースのメタ情報の取得

まとめ

・覚えやすく、どんな機能を持つかが一目でわかるエンドポイントにする。
・適切なHTTPメソッドを利用する。
・適切な英単語を利用し、単数形、複数形にも注意する。

最後に

今回は、主に「Web APIとは何か」ということについて書きました。
また追記します。