Update api.ja.pug

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を利用したい場合、
+		| 直接ユーザーのAPIキーをアプリケーションが扱うのは危険なので、
-		| ユーザーにアカウントへのアクセスを許可してもらい、ユーザーのアクセストークンを取得する必要があります。
+		| アプリケーションからAPIを利用する際には、アプリケーションとアプリケーションを利用するユーザーが結び付けられた専用のトークン(アクセストークン)をMisskeyに発行してもらい、
-	p アクセストークンを取得するまでの流れを説明します。
+		| そのトークンをリクエストのパラメータに含める必要があります。
+		| (アクセストークンは、ユーザーが自分のアカウントにあなたのアプリケーションがアクセスすることを許可した場合のみ発行されます)
+
+	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を利用することができなくなることがあります。