REST APIのドキュメントに書かれているもの

もし急にAPIドキュメントを書く必要が発生したら、何を参考にしたら良いのか。REST APIを提供しているサービスがどういった開発者向けドキュメントを提供しているのかについて調べた。今回対象としたサービスは、GitHub、Twitter、Square、DigitalOceanの4つのサービス。

• https://developer.github.com/v3/
• https://dev.twitter.com/docs
• https://developers.digitalocean.com/
• https://connect.squareup.com/docs/api

なお以下の文章の中では、個々のアクセス可能なメソッドとURLの組み合わせを指して「API」という言葉を使うことがある。例えば、GET /gists/:id という特定の投稿を取得するAPIや GET /gists/:gist_id/comments という特定の投稿に寄せられたコメントを取得するAPI、というように利用する。

Overviewの内容はほぼ共通している

GitHub、Square、DigitalOceanでは、ドキュメントの先頭部分にAPI全体に共通する情報を記載している。Twitterでは情報が分散しており、明らかにOverviewだと言える箇所は見当たらなかった。各Overviewには、共通して以下のような内容が記載されている。

• バージョン
• 入出力データの形式 (JSONであるとか)
• 日時の表記方法
• パラメータ
• 接続先のエンドポイント
• HTTPメソッド
• HTTPステータスコード
• エラー時のレスポンス
• 認証
• ページネーション
• リクエスト数制限

また、サービスによっては以下のような内容にも触れている。

• Cross Origin Resource Sharing
• JSON-P Callbacks
• Timezones
• メタデータ

APIごとの説明もほぼ共通している

ドキュメントではOverviewの説明のあとに各APIについての説明が続く。内容はサービスによってまちまちだが、主に以下の候補の中の一部の情報が記載されている。

• エンドポイントに関する情報
• APIに関する説明文
• リクエストパラメータの説明
• パスパラメータの説明
• レスポンスに含まれる値の説明
• 認証やページネーションとの関係
• サンプルリクエスト
• サンプルレスポンス

リソースごとにAPIをまとめているページでは、それぞれのAPIについてレスポンスの内容を説明するわけではなく、このAPIはこのリソースを返すという情報と、このリソースにはこの属性が含まれる、という情報がまとめて記載されている場合もある。

ページの分け方が異なる

GitHub

GitHubでは、リソースの種類ごとにページが分かれている。例えばユーザに関するAPIについては /v3/users に記載されており、Gistに関するAPIについては /v3/gists に記載されている。どのページにも表示されるサイドバーからページ間を遷移できるようになっている。また、タブ形式のナビゲーションから、Webhook APIについてのページや、API用のライブラリを紹介するページに遷移できるようになっている。

Twitter

Twitterでは、各APIごとにページが独立している。認証の種類やリクエスト数制限など、Twitterでは各APIごとの持つ属性が大きく異なる場合があり、またAPIごとに説明する必要のある情報量が多いため、細かくページが分かれている方が都合が良いと判断したのかもしれない。

Square & DigitalOcean

GitHubとTwitterはツリー状にページを分けていたが、SquareとDigitalOceanでは全てのAPIに関する情報が1つのページに収められており、サイドバーからページ内リンクを辿るようになっている。各APIは、リソースの種類別にまとめられていると言える。