エンドポイントは HTTPS リクエストを送る先です。GET、POST、PUT、PATCH、DELETE の各メソッドが、リソースとのやり取り方を決めます。
Title: エンドポイントのタイトルです。文頭だけを大文字にするセンテンスケースを使います。タイトルの末尾に句読点は付けません。単純な場合は、だいたい次のどちらかです。
単一の項目を扱う、または返すエンドポイント: 動詞 + 不定冠詞 + 単数のリソース名。
- 例: Get a list item
項目のコレクションを扱う、または返すエンドポイント: 動詞 + 複数のリソース名。
- 例: Get list items
Description: エンドポイントの動作、または使い方を説明します。説明の末尾は句点にします。
Plan availability: エンドポイントの利用に必要なプランを列挙します。Free、Pro、Business、Enterprise などです。
Method: GET、POST、PUT、PATCH、DELETE などのメソッド種別です。
Endpoint: エンドポイントを列挙し、コードスニペットとして整形します。
指定した時期に非推奨になるが、まだ使えるエンドポイントでは、説明に非推奨の予告を追加します（「<name of endpoint> will be deprecated on <full month name, date, year>. Use the <alternative endpoint> instead」）。詳細は 非推奨 API を参照してください。
Required permissions: エンドポイントの利用に必要な、ユーザーレベルの追加権限です。
タイトルと説明を書くときは、ボイスとトーンを意識します。簡潔に書き、読者の技術レベルがさまざまであることを忘れないでください。できるだけ能動態で書き、機械的な印象を避け、情報を理解しやすくします。
参考として、エンドポイントのタイトルと説明の例を示します。
- Get domain: 単一のドメインを取得します。
- List workers: アップロード済み Workers の一覧を取得します。
- List pools: 設定済みのプールを一覧します。
- Create waiting room: 新しい Waiting Room を作成します。
- Update health check: 設定済みのヘルスチェックを更新します。
Title: Get user audit logs
Description: ユーザーアカウントの監査ログ一覧を取得します。
Plan availability: Free、Pro、Business、Enterprise
Method: GET
Endpoint: user/audit_logs