diff --git a/src/web/docs/api.ja.pug b/src/web/docs/api.ja.pug index 588b926bd..dbe17fe66 100644 --- a/src/web/docs/api.ja.pug +++ b/src/web/docs/api.ja.pug @@ -1,25 +1,54 @@ h1 Misskey API -p MisskeyはWeb APIを公開しており、アプリケーションから様々な操作を行うことができます。 +p MisskeyはWeb APIを公開しており、様々な操作をプログラム上から行うことができます。 +p APIを自分のアカウントから利用する場合と、アプリケーションから利用する場合で利用手順が異なりますので、それぞれのケースについて説明します。 section h2 自分の所有するアカウントからAPIにアクセスする場合 - p 「設定」で、APIにアクセスするのに必要なAPIキーを取得してください。 + p 「設定 > API」で、APIにアクセスするのに必要なAPIキーを取得してください。 p APIにアクセスする際には、リクエストにAPIキーを「i」というパラメータ名で含めます。 p APIの詳しい使用法は「Misskey APIの利用」セクションをご覧ください。 section h2 アプリケーションからAPIにアクセスする場合 p - | あなたのWebサービスやアプリケーションなどからMisskey APIを利用したい場合、 - | ユーザーにアカウントへのアクセスを許可してもらい、ユーザーのアクセストークンを取得する必要があります。 - p アクセストークンを取得するまでの流れを説明します。 + | 直接ユーザーのAPIキーをアプリケーションが扱うのは危険なので、 + | アプリケーションからAPIを利用する際には、アプリケーションとアプリケーションを利用するユーザーが結び付けられた専用のトークン(アクセストークン)をMisskeyに発行してもらい、 + | そのトークンをリクエストのパラメータに含める必要があります。 + | (アクセストークンは、ユーザーが自分のアカウントにあなたのアプリケーションがアクセスすることを許可した場合のみ発行されます) + + p それでは、アクセストークンを取得するまでの流れを説明します。 section h3 1.アプリケーションを登録する p まず、あなたのWebサービスやアプリケーションをMisskeyに登録します。 - p デベロッパーセンターから登録を行ってください。 - p 登録が済むとアプリケーションのシークレットキーが入手できます。 + p + a(href=common.config.dev_url, target="_blank") デベロッパーセンター + | にアクセスし、「アプリ > アプリ作成」に進みます。 + | フォームに必要事項を記入し、アプリを作成してください。フォームの記入欄の説明は以下の通りです: + + table + thead + tr + th 名前 + th 説明 + tbody + tr + td アプリケーション名 + td あなたのアプリケーションやWebサービスの名称。 + tr + td アプリの概要 + td あなたのアプリケーションやWebサービスの簡単な説明や紹介。 + tr + td コールバックURL + td あなたのアプリケーションがWebサービスである場合、ユーザーが後述する認証フォームで認証を終えた際にリダイレクトするURLを設定できます。 + tr + td 権限 + td あなたのアプリケーションやWebサービスが要求する権限。ここで要求した機能だけがAPIからアクセスできます。 + + p + | 登録が済むとアプリケーションのシークレットキーが入手できます。このシークレットキーは後で使用します。 + | アプリに成りすまされる可能性があるため、極力このシークレットキーは公開しないようにしてください。 section h3 2.ユーザーに認証させる @@ -64,3 +93,7 @@ section h2 Misskey APIの利用 p APIはすべてリクエストのパラメータ・レスポンスともにJSON形式です。また、すべてのエンドポイントはPOSTメソッドのみ受け付けます。 p APIリファレンスもご確認ください。 + + section + h3 レートリミット + p Misskey APIにはレートリミットがあり、短時間のうちに多数のリクエストを送信すると、一定時間APIを利用することができなくなることがあります。