APIを設計する前に読みたいガイドラインまとめ

APIというのは主に外部の開発者が見ることになります。そしてその設計思想が彼らの思いとマッチしていないと使うのを嫌がられることになります。逆にエレガントで統一性のあるAPIは開発者を刺激し、使おうという姿勢に変えてくれます。
​
そこで今回は多くのAPIを提供している各社がリリースしたAPIガイドラインを紹介します。
​

interagent/http-api-design: HTTP API design guide extracted from work on the Heroku Platform API

​
Herokuが実践しているAPIデザインガイドになります。ステータスコード、リソース、タイムゾーン、パスの付け方、バージョニングなど数多くの項目に渡って記述されています。
​

API開発指針 | EC-CUBE3

​

​
国産Eコマースシステム、EC-CUBE3におけるAPI開発指針になります。日本語で書かれているので分かりやすいでしょう���
​

これから始めるエンタープライズ Web API 開発 | オブジェクトの広場

​

​
エンタープライズAPI設計における注意点がまとまっています。使いやすさ、分かりやすさ、安全性、堅牢性、耐障害性などエンタープライズならではの説明があります。
​

Web API設計指針を考えた | MMMブログ

​

​
MMM社によるAPI設計指針をブログで公開しています。URL、レスポンスなどについて記述されています。
​

WhiteHouse/api-standards

​
ホワイトハウスのAPI標準です。オープンデータを進める上でもこうしたドキュメントが公開されていることで一貫性をもった提供が期待できるはずです。
​

api-standards/api-style-guide.md at master · paypal/api-standards

​
PayPal社のAPIスタイルガイドです。複雑なオペレーションにおけるリスクとメリットなどは参考になる点がありそうです。
​

18F/api-standards: API Standards for 18F

​
18Fというのは米連邦政府のテクノロジーチームだそうです。彼らのAPI開発におけるベストプラクティスがまとまっています。
​

refinery29/api-standards: Refinery 29 API Standards

​
ソートやページネーション、モックレスポンス、検索など実用的なAPIにおける標準がまとまっています。
​

API Design eBook

​

​
ApigeeによるAPIデザインの電子書籍（PDF）になります。2012年のものですが、内容的には現在でも十分通用するものになっています。電子書籍なのでリーダーに入れて読むのに良さそうです。
​

API Design Guide — API Design Guide 0.1 documentation

​
オーストラリアのシドニーとキャンベラによるAPIデザインガイドです。開発およびその利用に関する説明があります。

​

​
企業がAPI設計指針を作ると言うことは統一感を作り出すのに大事なことでしょう。また、その設計時においてはここで紹介したコンテンツが役立つはずです。将来的にはこうしたコンテンツをベースにしたLint系ツールが出てくるかも知れません。
​
開発者を魅了する、魅力的なAPIを提供するためにも設計のいろはは習得する必要があるでしょう。ぜひ参考にしてください。