November 2014
Intermediate to advanced
224 pages
3h 22m
Japanese
Web APIを公開するにあたって、Web APIそのものを構築する以外に、そのAPIを利用する開発者がより楽に利用できるようにするために、やっておいたほうがよいことがいくつかあります。ここではそういった事柄を紹介します。
APIを構築する際に必ず考えなければならないのは、そのAPIの使い方を示したドキュメントを用意することです。ドキュメントがなくては、開発者はAPIへのアクセスの仕方がわかりません。もし同じチームでサーバとクライアントを書いており、クライアントのエンジニアがサーバのコードにアクセスできるのであれば、コードを読んで仕様を理解するという方法も考えられますが、第三者に公開するAPIではそういうわけにはいきません。したがってきちんとしたドキュメントを提供することは、公開したAPIを多くの人に利用してもらえるようになる第一歩といえます。
ドキュメントを公開するにあたって注意すべきことは、APIのドキュメントをきちんと常に最新にしておくことです。これはWeb APIに限った話ではありませんが、開発の際にドキュメントの更新が後回しになった結果、実際のAPIとドキュメントの内容に差異が生じるといったことがないよう注意する必要があります。
API Blueprint(http://apiblueprint.org/)というWeb APIのドキュメントを書くための記法も存在しています。これはMarkdown記法を使ってAPIの仕様を記述するものです。
# Gist Fox API Root [/] Gist Fox API entry point. This resource does not have ...