APIの定義とジョークAPI
ITエンジニアの雑談駆動開発部。 この番組は、同い年、岡田エンジニアの二人が技術のこと、キャリアのことを等身大のまま語り合っていく番組です。
成長中の二人が学んだことをリアルタイムでお届けします。 使用書なし、テストなし、雑談だけで駆動していきます。
ITエンジニアの雑談駆動開発部、始まります! イエーイ!
始まりました! また、噛まずにいました!
ナイス滑舌! じゃあ、もう早速帰っていきますよ。
APA叩いてますか? もう、殴ってます。
ぶん殴ってます。 APA叩くってなんか可愛いですよね。
怖くないですか?ちょっと。 叩くってなんか珍しくないですか?
うんうんうん。 まあ、それだけなんですけど。
実行するとかでいいですよ。 本当は実行するんだけど、叩くってなんかオシャレなのかわからないですよ。
ヒットがAPAみたいなのから来てるらしいですよ。 えー、そうなんだ。
わかんないけど、どっかで聞いた気がします。 あ、そうなんですね。
APA作ってますか? API、そうですね、作ってますね。
APAって何ですかね? 言っちゃっていいんですか?
今回のテーマでもある、ちょっとAPAの話ね。 結構真空ったこと言えるかもしれない。
いいですか? じゃあ、いったん言ってください。
APIは入り口? 入れるものを決めちゃったら
その入り口の定義通りのものを入れたら 決まった答えが返ってくるもんね。
これがAPIかなって。 いいと思います。
今回のテーマなんですけど、 ウェブAPIの本
ウェブAPI The Good Parts 水野孝明、超オライリージャパン2014年のやつを持ってきたんですけど
読んできて、これはバックエンドエンジニアとして我が家なりにも言わせていただいているので
APIの基礎、根拠を持って話せないといけないなというふうに思いましたので、 今回読ませていただきました。
めっちゃ読んでますよね。 読んでます。
本になっちゃいますよ。 本当だ。
すみません。
今回はAPIの正解をたどり着くたくて、 APIの正しいものとは何なんだっていうのを
知りたくて、今回読んだんです。 ということで、まずAPIとは定義をさらっていきますと
この本的には、中身の実装を知らなくても外部から機能を呼び出せるようにするための 仕様のことを言うそうで
APIの略って Application Programming Interface
その中身を知らなくても外部から機能を呼び出せるようにする仕様のことを言うらしくて
Web APIはそのAPIをHTTPというネットワーク越しに呼べるようにしたものを Web APIって言うらしいです。
違いがあるんだ。 人がブラウザで見るウェブページと違って、プログラムがデータを機械的に使うのが前提となっています。
その時に扱われる形式はJSONがよく使われていますよね。
入力でJSON入れて帰ってくるのもJSONみたいな。
自分の言葉でなんとなくまとめるとネットワークを使って外部からアプリの機能を呼び出せるようにするような仕様
自分の使っているウェブサービス以外のところからのものを呼び出せるようにするような仕様機能のことを言ってるのかなって思ってて
UIって言うじゃないですか。ユーザーインターフェースって言うじゃないですか。
これのほぼ対義語だなと思って。 UIってユーザーが使うインターフェースじゃないですか。
APIってアプリケーションが使うインターフェースなんで。
これ対義語だなと思って。
そうですね。なるほど。わかりますね。みたいなこと。
なんかそんな感じじゃないかなと思って。
わかりますわかります。
ユーザーは人が使う窓口、APIはプログラムが使う窓口みたいな感じですね。
あれですかね。関数とかもAPIって言えるんですかね。
確かに。それはそれで言ったら中身を知らないっていうのが条件になってくるから。
関数は自分で書いてたらわかるじゃないですか。
だから厳密には違うのではないかという話をしてました。今。
見えない関数。
中身が見えなくても使えるっていうのがもういいっていう。
でも身近な例で初めてAPI叩いたのがあって。
初めてAPI叩いたのを明確に覚えてるんですけど。
このジョークAPIってやつを叩いたんですよ。
初めて聞いた。
このAPIを投げる。リクエストを投げるとアメリカンジョークが返ってくるっていう。
面白い。
これちょっとリンクを載せるんで叩いてみて欲しいんですけど。
例えば一個例があって。プログラマーのジョークみたいなやつがあって。
これ結構面白いので聞いて欲しいんですけど。これちょっと聞いてくださいね。
英語で一回言う。
なぜパイソンのデータサイエンティストは税関で捕まったんですか?
これアンサーが
She was caught trying to import pandas.
パンダを輸入しようとして捕まった。
あははははは。
あははははは。
これ意味わかりますか?
あれですよね。パンダってパイソンのフレームワークですか?
パッケージみたいな。
データ分析するときに使うパンダをインポートパンダって頭に書くじゃないですか。
それになぞって彼女はパンダを輸入しようとしたので税関で捕まったっていうアメリカンジョーク。
あははははは。面白い。
やだ、悪い言葉だな。
もう一個いきます。
How did you know God is a city programmer?
なぜ神はクソなプログラマーなんだって質問ですね。
He wrote the OS for an entire universe, but didn'tleave a single useful comment.
彼はこの世界というOSを作ったんだけど、一言も有用なコメントを残さなかった。
わかりますよ。
回収しようと思ってもプログラムしかないからしづらいってことですか?
そもそもそうだし、何のコメントも残ってないからこの世界の使い方がわからないみたいな。
神様がOSというこの世界を作ったけど一つもコメント残してないからみんなどうやって生きていいかわからないよみたいな。
あははは。
いいのはいいんですけど。
なんかイカしたジョークですね。
中身の仕様はわかんないけど、とりあえずリクエスト送ったら外部のサービスが使えるようになったじゃないですか。
外部のジョークが返ってくるAPIが返ってきたみたいな。
中身何してるかわかんないですね。
どうやってこのジョークを作ってるのかわかんないし。
ですね。更新してるのかな?
そうですね。
AIのジョークが返ってきた。
みたいなのがAPIですね。
美しいWeb APIの4条件
この本の中に話に移るんですけど、美しいWeb APIの4条件を紹介されていて。
まず一つ。
この本の大筋としては美しいWeb APIとは何かっていうところがあったんですけど、まず一つ。
使いやすい。
利用する開発者に負担をかけない。
もう一つが変更しやすいこと。
仕様を変えても利用者への影響が小さい。
眼鏡であるセキュリティ上の問題が起きにくいこと。
最後の一つが恥ずかしくない。
開発者から見て恥ずかしいようなAPIを作るなんて。
どういうことだろう?
まあまあこれはね。
さっきのジョークのやつとか恥ずかしいやつってことですか?
ジョークがちょっと渋かったら恥ずかしいのかもしれないですけど。
あれかな設計的に微妙っていう。
まあそういうことですね。
めっちゃ遅いとか。
かも。
設計者として他の開発者が見たときにどうなんだっていうのがないようなのが美しいAPIの4条件と言われています。
URIとHTTPメソッドの設計
で、まず使いやすいっていうところなんですけど。
まず使いやすいっていうのは何なんだっていうところで。
まずは美しいURIっていうのを用意していて。
これURIっていうのはこのドメインの後につくスラスラのスラのところです。
URIっていうのが渋いですね。
この美しいURIっていうのは覚えやすくてどんな機能が一目で分かるもの。
例えばユーザーを取得したいときに何とか何とかYouTube.comスラユーザーだったらユーザー取ってくるんだなって一発で分かるじゃないですか。
じゃなくてそのYouTube.comスラに出せたらこれ何を持ってきてるのか分かんないじゃないですか。
こういうときにこのURIを見て一目で大体どんな機能かなって分かるものを美しいURIと定義しています。
逆に動詞とか入ってたら分かりづらいですよね。
だから一発で分かるようにするっていうのが大事。
で、もう一つあるのが改造しやすいってところ。
例えばアイテムなんかの商品とかをいったときに商品にアイテムズスラッシュ111ってなってたらアイテムズスラッシュ112には別のアイテムが入ってそうだなみたいな。
こういう仕組み設計になっていることによって改造しやすいっていうのが使いやすいっていうのがもう一つ。
で、残りのもう一つは短い、読める。
先ほど言ったような単語を使ってないとか動詞を使ってないとか。
この短くて読めて小文字で…ちょっと残りの条件が多いんだけど。
短くて小文字で統一されていて単数複数は混ぜないみたいな。
ある一方のときにはアイテムを使っててもう一つのときにアイテムズ使ってたならどっちなんだって混同しちゃうじゃないですか。
そういうことをやめましょう。
どっちかに使うなら統一。
っていうのが美しいURI。
覚えやすいとかも近いかもしれないですね。
もう一つ使いやすいには条件があって、HTTPメソッドの使い分けをしたいんですよ。
URIは操作する対象で、HTTPメソッドっていうのは何をするかっていうのを決めています。
簡単に言ったらGETは取得、POSTは新規登録、PUTは全体を置き換えて更新、PATCHは部分更新、DELETEは削除って言われてます。
PATCHとかあんまり聞いたことないですね。
そう。PATCH部分更新です。
あんまり見ないかもしれない。
あんまり見ないかもしれない。
で、べき等性っていうのがあって、これは同じ動作を何回繰り返しても同じ結果が得られる性質のことです。
で、PUTはべき等性があります。
全体を置き換えて更新してる。
例えば、データベースに太郎さんっていう名前が入ってたとして、太郎さんの名前を二郎さんに変えたいとき、
これPUTリクエストでやると、太郎さんを二郎さんに変える、PUT、二郎さんになりました。
で、これを何回PUTで送ったとしても二郎さんが一人いるだけなんですけど、
これがPOSTで送ったときは、POSTっていうhttpメソッドの基本的にべき等性がないものなので、
二郎さん、POSTで太郎さんを変えようとしちゃうと、二郎さん、最初の一発目は変わるんですけど、
その後に二郎さん、二郎さん、二郎さんって三回送ると、二郎さんが三人出現しちゃう。
っていう性質がある、POSTは。
っていうところを覚えておく。
PUTだったら、太郎さんを二郎さんに変えても、その後佐藤さんとか竹井さんになることはない。
絶対二郎さんだって。
REST APIって聞いたことありますか?
聞いたことあります!
REST APIのRESTって何かわかります?
なんだろう?なんだっけ?
これRESTは、簡単に言ったらルールの話なんですよ。
これはこうするべきだっていう。
このRESTっていうルールがあって、それをみんなで守ろうっていう風になってるんですよ。
で、httpはもう決まってる法律みたいな話で、
httpはPUT、GET、POSTとかの法律で決まってる、完全に決まってる道路交通法みたいな。
赤は止まると決まっているみたいな感じで、
RESTはみんながこのPOSTっていうものを、
適当性がないものだと理解して使うことが大事だよねっていうバイブルみたいな。
考え方のフレームワークなんですね。
PUTは適当性がある。
POSTは適当性がないよね。
だからこの処理にはPOSTを使わないといけないよねっていうルールの話。
これがREST。
で、REST API。
だからそのRESTのルールに基づいたAPIっていうのをREST APIっていうらしいです。
で、RESTって何の略なんですか?
略がわかんない。
なんだよ!
略がわかんない。
なんかね、調べましょう後で。
家に行けばいいですかね。
なんかRESTルールみたいなのどっかにあるらしいです。
自分一回それさらいましたよ。
今もう完全に守るの難しいらしい。
そうなんだ。
URLは絶対変えましょうみたいなルールが確かあったはず。
だけどREACTORとか使ったらURL変わんないから、完全に守るのは難しくなってるよねみたいな。
ああ、そうだった。
クラウドらしいですね。
いいこと聞いたかも。後で詳しく教えてもらう。
RESTのルールの中に動詞を入れちゃいけないとこもあるらしいですね。
そうそうそう。
レスポンスデータを使いやすくする
で、もう一つ使いやすいものの中に使いやすいAPIは何かってところで、
レスポンスデータの設計っていうのがあります。
はい。
これもうなんとなくの、これ絶対なルールじゃないんですけど、
監修的に決まっているものとして、最近はデータ形式をJSONが基本です。
もともとはXMLとかを使ってた時代があったっぽいんですけど、
今はほぼほぼJSONでみたいな、大体のルールになってるっぽいです。
これなんかリクエストヘッダーとかにアプリケーションすらJSONみたいなの入れるじゃないですか。
あれで指定してるらしいんですよ。
コンテンツを。
そうそうそうそう。
あれで指定してます。
で、これデータ構造の考え方なんですけど、
これ一つの画面を出すのに何度もAPIを呼ばせないようにしたいんですよ。
このAPIって呼ぶたびに通信するんで、呼びすぎると時間もかかっちゃうし、
物によってお金かかっちゃうじゃないですか。
別に人のやつだとお金取られます。
なので一つの画面を出すのに何度もAPIを呼ばせないような設計にしないといけない。
データ構造にしないといけない。
DBのデータをそのまま返すのはAPIに求められるものではないんです。
例えばユーザーのデータとか取るときに、
テーブル上はユーザーテーブルとか、ユーザーテーブルと商品テーブルあるじゃないですか。
テーブルのデータ構造をそのままAPIとして持ってきちゃったら、
ユーザーを取って商品を取らないといけないじゃないですか。
じゃなくてAPIとしては、
このユーザーがどんな商品を持ってるか一発で呼べるようにするデータの考え方。
まとめて返しちゃうんですね。
データ構造をそのまま反映させないっていうのが大事。
JSONの形式をなるべくフラットにする。
入れ子になってると実装するときに、
あれの中のあれのみたいな取り方をするじゃないですか。
これはできるだけしたくないじゃないですか。
なんだかよくわかんなくなっちゃう。
っていうのを避けるためにデータ構造としても、
作る側がそもそもできるだけフラットにするっていう考え方が大事で。
ありましたよね。
フロントエンドとバックエンドで違う人が作ったら、
なんだよこれ。
入れ子になってると。
あとは取得する項目や件数を利用者が選べるようにする。
一件だけデータが欲しいのに一覧で来ちゃった。
一覧しかない取得する機能がなかったら、
利用する側としては一件だけ欲しいのに、
毎回毎回全部のやつを取得して、
自分でアプリの中で絞って使わないといけないんで、
そういう場合にはしっかりと取得する項目や件数を利用者が選べるような
仕組みを作っておくことがデータ構造の考え方として大事ですと。
早くシンプルに使いやすいデータを返すための構造が並んでいるような感じにしないといけなくて、
みんなが使うものだからできるだけ簡単にしておきたいなっていうのが
データ構造の考え方かなと思います。
使う人を考えるって感じですね。
使う人を考えるって感じ?
抽象的にシンプルねみたいな。
そう。
URIもメソッドもレスポンスも全部使う人が迷わないための設計をするっていうのを
先頭に置いておくことが大事ですねっていう。
めちゃくちゃ難しそうですね。
そう。
難しそうだよね。
難しいですよね。難しいんだ。
変更とバージョン管理
で、もう一つの美しいWeb APIの条件として変更しやすいもの。
APIは一度交換したら使われ続けることに意味がある。
そのサービスなんで。
でもAPI公開後は想定外の使われ方や機能追加は珍しくないことで。
仕様が突然変わると利用者全員が修正しないといけなくなるような設計にはしたくないですよね。
APIを使っている人が。
そうですね。プログラムが読み出すものですもんね。
回収しなきゃこっちも嫌いになるからたまったもんじゃないですか。
で、これバージョン管理っていうのがあるんですけど。
たまにV1、V2とかURLの間に挟まってるじゃないですか。
これが俗に言う変更せざるを得なかった時にV1からV2に変えてるみたいなのがあるんですけど。
これバージョンを上げたら提供側も利用者側もコストがかかるじゃないですか。
2人とも使ってる人も直さないといけないし、作ってる人もバージョン上げないといけないんで。
基本は上げたくないんですよ。
できるだけ上げないようにしたい。
で、上げるべき変更っていうのがあって。
上げるべきは前提そのものが変わって、バージョン1とバージョン2が共存できないときは上げる必要がある。
一番怖いのはやっぱりLRにならずに黙って会社って誤作動するのが一番嫌なんで。
上げるべき変更の時はしっかりと事前通知が大事ですよね。
例えばなんですけど、金額を返すAPIとかだったりとして金額の計算方法が変わっちゃったりとか。
税率とか。
税抜きから税込みに代替えますよって言ったら、それもともと税抜き前提でアプリ使ってる人は使ってるのに勝手に税込みに変えられちゃったら困るじゃないですか。
そういう時にはバージョン上げて代用しようみたいな場合もあるらしい。
逆に上げなくていい場合。
これは項目を追加した時とか。
クライアントがAPIを使っている人が追加されただけなのであれば、追加されたものはそもそも自分たちのアプリには取り込んでないんで。
来てるけど使ってない状態。
エラーにはならない。
だからバージョンは上げなくてもいい。
返すものは増えただけだから。
入れるほうが変わんないですもんね。
どんだけ追加する分にも別にお客さんのAPIには特に影響なさそうだみたいな時は上げなくてもいい変更。
これは基準としては黙って変えた時にクライアントで壊れるかどうかが基準ですね。
そうか。返すもの変わったら逆に反映されなかったりしますもんね。
そこはやめてほしいですね。
最初の設計でそれをできるだけ、後々は追加だけにできるような設計を考えたい。
呼び出す側にも責任があるんですね。
API終了とセキュリティ
これが今APIを追加したり回収したりする話なんですけど、APIの提供を終了する時もあるじゃないですか。
もう使わせませんみたいな。
サービス終了しちゃって。
っていう時にはこれ事前通知をしましょう。
ああ、そうですよね。いきなり使えなくなったの。
ツイッターで昔あったらしいんですけど、ツイッターのバージョン1.0を配信する時に6ヶ月前から告知したらしいです。
親切。
6ヶ月前に告知して、一時的に6ヶ月内で直してくださいみたいな話ですよね。
ああ、そうですね。しっこ言うよみたいな。
その途中にブラックアウトテストみたいなのをやって、意図的に使えなくするみたいな時間を設けつつ、完全にスパッとやめる前に一瞬使えなくして、また戻してみたいなブラックアウトテストみたいなのをするらしい
です。
ああ、そうなんだ。
これでブラックアウトテストした時に、やってなかった人は気づくんでしょうね。
何かやられてるぞみたいな。
アドナイトみたいなことをすることもあるらしいです。
結構至れり尽くせりですね。やっぱり大きいシステムだと。
で、終了した場合はhttpリクエストを4105にするらしいです。
ええ、そうなんだ。知らなかった。
これどの意味だったか忘れたけど、確かもうこのページはもうすでに無くなりましたみたいな意味らしいです。このhttpコード。
4105音。
まあ何事も大連鎖が大事ですよねっていう話です。
変更も終了も全部使う人の困らせないために考えて作っていきましょうって話です。
ホスピタリティですね。
うん。
で、もう一つ美しいAPIとは眼鏡であること。
硬いみたいな。
硬い。
すいません。眼鏡ね。
セキュリティの話ですね。
APIを使った時に脆弱性とかセキュリティみたいなところはないようにしようっていう話です。
ネット越しに誰でもアクセスできるものなのでセキュリティと備えが必要ですよっていう話。
で、例えばその中間攻撃ってものだったりXSSであったり。
クロスサイトスクリプティングです。
じゃあこれは?XSRF。
ああ、ちょっと今思い出すんです。
たぶん略だけ知ってるのはクロスサイトリクエストポージェリーですね。
この話はセキュリティの話なので一旦置いておいてこういうのを気をつけましょうって話です。
大量アクセスの対策とかね。
しっかり対策することによって美しいAPIになっていきますよっていう話です。
これも使う人を守るため。
恥ずかしくないAPIと思いやり
で、これ恥ずかしくないっていう話だったじゃないですか。
思いました。思いました。
美しいAPI恥ずかしくないとは?
これは開発者から見て恥ずかしくないっていう。
ああ、やっぱり。
設計に違和感がないであったり。
APIの質がそのAPIを作った会社や技術者の評価につながります。
やっぱ性能なんですかね。
性能。
遅いとか言われます。
これね、会社の評価につながるって話ですね。
観点としてはすごい面白いじゃないですか。
恥ずかしくないっていうの。
でもいざ自分がやられるときに恥ずかしくないっていうのを作れるのかっていう。
いや、そうですよ。
自分がかっこいいと思ってても、ちゃんとできたと思ってても。
他の人が見てって話じゃないですか。
なんだこれって言われるかもしれないし。
世の中のAPIをある程度知らないと自分のAPIがどう映るのかを客観的にわからないじゃないですか。
だから勉強してるんですよ。
恥ずかしいのね。
作らない。
これ正直ね、今記事を書いててね。
動画を話してて、なかなか映るじゃないですか。
恥ずかしいですね。
多くを知らないと。
たださっき言ったような、使いやすいやったりとか変更しやすい環境のこの3つができていれば、ある程度恥ずかしくないAPIなんじゃないかなと思って。
この4つ目の恥ずかしくないを達成するために、さっきの使いやすい、変更しやすい環境っていうのを守る必要があるんじゃないかなっていう。
さっきの恥ずかしくないってなんだっていう定義ですね。
なるほど。
最初の3つができてたら恥ずかしくなくなるよみたいな、まとめなんですね。
なのかなというメッセージを感じ取りました、私この文字から。
そうかもしれないですね。
まとめに入るんですけど。
正解を知りたくて読んだんですよ、このWeb APIとはみたいな。
確かに使いやすいとか変更しやすいとかなんとなく成功はあって、知識として覚えていく必要はもちろんあったと思ったんですけど。
でもこのスタンダードってそもそも誰が作ったんだみたいな話があるじゃないですか。
使いやすいって決めたのは誰みたいな。
使いやすい変更しやすいっていうのは時々今まで作り上げてきた歴史の中でその時の開発者がこの方が使いやすいかなっていうのがルール化されてると思うんですよ。
その時々に使いやすいのは何かなっていうのを開発者が考えてそういうのを考えた結晶が今のAPIになってきてるんですよ。
レストとかもそうなんですね。
そういうルールとかも使う人のことを考えたAPI、使う人のことを考えたルールの上で私たちは生かされているという。
この本の中でも企業ごとにいろいろなちょっとずつ仕様の違いだったりとかルールがそれぞれの企業ごとにAPIって異なってるんですね。
みんなのハウトゥーがあるんですね。
そう。だからこれっていう正解はそもそもないんですよ。
例えばどっかの会社はJSONを使ってる。どっかの会社はJSONを使ってないとか。
スタンダードはJSONだけど別に使ってなくてもいいみたいな。
これっていう正解がないんですよね。
みんなそれぞれの正解があるんですね。
そうなんですよ。
これWeb APIの正解を探しに行ったんですけど、今回は思ったこととして正解を探しに行ったら正解は使う人への思いやりです。
そうじゃないですか。
そう。APIの正解は思いやりなんですよ。
相手のユーザーさんの気持ちを考えてみたい。
そう。どうやったら使いやすいかっていう考えることがAPI設計になっている。
まとめがいいですね。
だからスタンダードには従いつつ、自分は常に使う人のことを考えた設計をするっていうのが大事だよねっていうことを今回学びましたというお話です。
人を考えるプロダクト設計
なんか自分もITの勉強すればするほど、システムとかITとか理系分野の話ってちょっと冷たい印象ないですか?
ロボット的というか。すごい合理的なものなのかなって思うけど、その本質を掘っていったら結局は人みたいな。
結局人が作ったルールだから。
人が作ってどう使いやすいかみたいなのを考えたルールの上でやってるみたいな。
結局いいプロダクトも人のことを考えるとできるんです。
そういうことです。
前、勉強し始めたときに、本格的にやり始めたときに聞いた話で、Zoomってあるじゃないですか。
ビデオ通話の。
Zoom作った人って家族と地理的に離れてるらしくて仕事で。
でも地理的に離れてるけど会話とか、ほんとその場にいるような形で家族とも接したいよねみたいなことで作ったのがZoomらしくて。
なんかそういう合理的とは反対側。
すごい思いやりとか愛情みたいなところからいいプロダクトが生まれるのかなってこのまとめを聞いてやっぱり思いましたね。
ありがとうございます。まとめていただいて。
さあ、まとまったところで。
ちょっと今回ね、この読んだ記事についてちょっと感想とかを記事にまとめたので。
概要欄に載せてますんで。
説明欄か。
ちょっとぜひ見ていただきたいなと思います。
ということで今回は美しいAPIの話でした。
なんか好きな内容だったら面白かったです。
ありがとうございました。また来週お願いします。