仕事でAPI設計を行なっているため、この機会にAPI設計について人生をかけて学び習得しようと思い購入した書籍、それが「Web API The Good Parts」。
API設計に関して、優秀なエンジニアの方にご質問をさせていただいた際に多くの方が「この本読んでみたら」と言っていた本。
さっそく購入して読んでみたらマジで良書だったので、ここにまとめておこうと思う。
良いエンドポイントの設計についてをここにはまとめておく
この書籍で学んだことを全てまとめることも考えたが、この記事では重点的に「良いエンドポイントの設計」というものについて簡潔にまとめておこうと思う。
APIのエンドポイントを考えていくなかで、基礎であり、原則となるものだからここはしっかりと押さえておきたい。
良いエンドポイント(URI)の設計とは
良いエンドポイント(URI)の設計
これに関しては、以下のようなことが挙げられていた。
- 短く入力しやすいURI
- 人間が読んで理解できるURI
- 大文字小文字が混在していないURI
- 改造しやすいURI
- サーバー側のアーキテクチャが反映されていないURI
- ルールが統一されたURI
これらを1つずつ簡潔にまとめておく。
短く入力しやすいURI
これは、そのままで短くて、入力しやすいものにするということだ。
「短くて、入力しやすい」ということは、シンプルで覚えやすいということにつながる。
長いURIは往々にして不要な情報やいくつかの同じ意味が重複していたりするため。そのため、シンプルな方がいい。
このURIには、「api」と「search」という言葉が入っていて、なんらかの検索用のAPIだということが予想できる。さらには「service」という言葉も含まれている。
しかし、このURIはもっとシンプルにすることができる。
http://api.example.com/searchこのURIでも、「検索用API」であることは安易に予想がつく。
このように同じことを表しているのであれば、短くてシンプルな方が、理解しやすく、覚えやすく、入力間違いなども少ないはず。
人間が読んで理解できるURI
うえで説明したみたいに、
http://api.example.com/searchこのようなURIであれば「検索APIだな」とだいたい予想ができる。
しかし、以下のようなURIだと果たしてどうだろうか。
http://api.example.com/sv/u/たしかにapiと入っているため「api」であることは予想がつくかもしれないが、「sv」も「u」もなんのことだかわからない。「sv」はserviceのことかもしれないしれないし、「u」はuserのことなのかもしれないが、確信を持つことは難しい。
このようなURIを生み出してしまわないために省略形は使わないことにしよう。
