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}",
とても親切で分かりやすいです。