APIの使い方をAPIで説明する

投稿日: by keruu

APIを開発していると、自分でもAPIの使い方を忘れてしまうことがあります。そんなときは使い方を返してくれるAPIがあると便利です。

事例

事例としてGitHubのAPIが参考になります。

次のGitHubのAPIのルートにアクセスすると、利用可能なAPIの一覧を返してくれます。

https://api.github.com/

こんな感じで返ってきます。

{
  "current_user_url": "https://api.github.com/user",
  "current_user_authorizations_html_url": "https://github.com/settings/connections/applications{/client_id}",
  "authorizations_url": "https://api.github.com/authorizations",
  "code_search_url": "https://api.github.com/search/code?q={query}{&page,per_page,sort,order}",
  "commit_search_url": "https://api.github.com/search/commits?q={query}{&page,per_page,sort,order}",

  (省略)

  "user_organizations_url": "https://api.github.com/user/orgs",
  "user_repositories_url": "https://api.github.com/users/{user}/repos{?type,page,per_page,sort}",
  "user_search_url": "https://api.github.com/search/users?q={query}{&page,per_page,sort,order}"
}

これならAPIの使い方を忘れてしまっても安心です。

APIの使い方をどんな感じで表現しているのか見てみます。

基本的な表し方

"URLの説明": "URL"
"current_user_url": "https://api.github.com/user"

オプショナルなルーティングがある場合

"URLの説明": "URL{/オプショナルなルーティング}"
"gists_url": "https://api.github.com/gists{/gist_id}"

任意の文字列が入る場合

"URLの説明": "URL/{任意の文字列}"
"user_url": "https://api.github.com/users/{user}"

オプショナルなクエリパラメータがある場合

"URLの説明": "URL{?パラメータ1,パラメータ2,パラメータ3}"
"current_user_repositories_url": "https://api.github.com/user/repos{?type,page,per_page,sort}",

とても親切で分かりやすいです。

API