Web API The Good Partsから学ぶAPIの設計

こんにちは、いっとくです。

絶賛API勉強中です。

いきなりただの愚痴なんですが、APIという言葉は本当に理解しづらいと思う。

Application Programming Interfaceの頭文字を取ってAPI。まずこの元になっている単語が直感的に猛烈に理解しにくい。

アプリケーションもプログラミングもインターフェースも全部珍しくない単語なのに、合体した瞬間全然意味がわからなくなるから不思議です。

僕はエンジニアになる前はIT系の営業をやっており、APIという単語には昔から頻繁に触れ合っていたのですが、聞く度によくわからなくて、調べては「サービスをつないでる窓口みたいな感じかぁ…え、どういうこと？？」ってなっていた記憶があります。

エンジニアになってAPIを使うようになってから初めて意味がわかるようになりました。

APIという単語を知らない人はリクエストとレスポンスの意味を調べてから意味を調べると掴みやすいんじゃないかなぁと思う。

まぁそんなことはさておき、僕はエンジニアになってからもずっと画面があるWebサービスを開発しており、そのサービスはAPIを提供しておらずSPAでもなかったので、全くと言っていいほどそのお作法がよくわかりませんでした。

ただ、ちょっと業務でAPIの知識を持つ必要性に駆られたので、こちらの書籍を購入し、お勉強しました。

ヘビかっけぇー。何なんでしょうね、このオライリー本の独自のブランド感。最近オライリー本欲しい病にかかっている気がする。

タイトルから、APIの良いパターンをポツポツ紹介している感じなのかな？と思いながら買ったのですが、APIを作ったことがない人に向けて、どのようなAPIが使いやすく美しいのかというのを懇切丁寧に解説している良書でございました。

Webアプリケーションの開発経験がある人であればこれを読めば、ある程度のAPIのお作法がわかるようになると思います。

具体的には、まずAPIとはどんなもので、どんなサービスに必要なのかという全体のイメージから始まり、ユーザーが使いやすいエンドポイントの設計や、レスポンスデータの設計、HTTPの活用方法、アプリケーションのバージョン管理からセキュリティまで、本当に全部わかりやすく書かれています。

特に、僕はこれを読むまでオリジンとかエンドポイントとかその辺のWebアプリケーションの開発であれば触らなくても生きていける部分の知識がほぼ皆無だったのですが、これを読み終わった今ではエンドポイントはAPI側で用意しているURLだってことはもちろん、クロスオリジンリソースシェアリングという概念が存在しており、その場合特定の条件でリクエストを飛ばさないとプリフライトリクエストというのが飛んじゃうよ？？みたいな仕様のところまで説明できるレベルにはなりました。

本自体はそこそこ薄いのですが、その薄さとは裏腹に読後の知識の増え方は尋常じゃなかったように思えます。特濃の内容でした。っていうかオライリー本ってページ数あたりの情報量多いので、薄さと読みすすめる時間も一致してなかったような気はする。

Q.ズバリ美しいAPIとは？？

A. 意表をつかないありきたりな設計

これだと思うんです。

美しいAPIを作るには、使いやすいエンドポイントの設計や、見てわかるレスポンスデータの構造と、ドキュメントあたりがかなり肝になるんじゃないかと思います。

しかし結局どれもデファクトスタンダードとなっている仕様に沿って作られたものというのが、世の中のユーザーが使いやすい美しいAPIになるというが結論です。

これはAPIに関わらずあらゆる製品にも言えると思いますが、身の回りの製品って説明書ついてますが、説明書がなくても使えることが非常に多いと思うんです。それは直感的なデザインがそうさせる場合と、およそ他の商品と共通しているからわかるという場合があると思うんです。

要はAPIもそれと同じで、直感的に見てわかるエンドポイントを書き、多くのサービスが使っているレスポンスデータの構造に合わせるというのが、説明書を読まなくても使えるAPIだと思うんです。そしてそれがユーザーに取っては一番使いやすい。

APIは歴史が浅いので、まだ定まりきっていないという部分もあるため、これが革命的に使いやすそうだと思いついたものは使ってもいいと本書にもありますが、実際にそんなひらめきが降りてくることは少ないでしょう。

いや降りては来るのですが、後で見返した時になんていう設計にしたんだ、過去の俺ェ、、、ってなりそう。

そして、その具体的なデファクトスタンダードを学べるというのがこの「Web API The Good Parts」という本なのです。

エンドポイントに使う単語や、RESTfulな設計、HTTPの仕様にあるものはHTTPの仕様に任せる、そして各ヘッダー項目の知識など幅広く学ぶことができます。

そんなわけで、めっちゃおすすめです。

特に開発経験があるけど、APIを設計したり作ったことないという人は学ぶことが多く、しかも読み進めやすい内容です。

エンドポイント設計やレスポンスデータの設計、その他セキュリティ周りで気にすべきことがわからないとか、クロスオリジン…？？なんていうところでお悩みの場合は一気に解決できると思います

はい、というわけでWeb API The Good Partsの感想でした！

背表紙だと、Web API: The Good Partsになっているのですが、JSONレスポンスの形式をイメージしたんですかね？？

以上、いっとくでした！さようなら