1 files changed, 103 insertions, 0 deletions
diff --git a/src/client/docs/api.ja.pug b/src/client/docs/api.ja.pug
new file mode 100644
index 0000000000..665cfdc4b8
--- /dev/null
+++ b/src/client/docs/api.ja.pug
@@ -0,0 +1,103 @@
+h1 Misskey API
+
+p MisskeyはWeb APIを公開しており、様々な操作をプログラム上から行うことができます。
+p APIを自分のアカウントから利用する場合(自分のアカウントのみ操作したい場合)と、アプリケーションから利用する場合(不特定のアカウントを操作したい場合)とで利用手順が異なりますので、それぞれのケースについて説明します。
+
+section
+	h2 自分の所有するアカウントからAPIにアクセスする場合
+	p 「設定 > API」で、APIにアクセスするのに必要なAPIキーを取得してください。
+	p APIにアクセスする際には、リクエストにAPIキーを「i」というパラメータ名で含めます。
+	div.ui.info.warn: p %fa:exclamation-triangle%アカウントを不正利用される可能性があるため、このトークンは第三者に教えないでください(アプリなどにも入力しないでください)。
+	p APIの詳しい使用法は「Misskey APIの利用」セクションをご覧ください。
+
+section
+	h2 アプリケーションからAPIにアクセスする場合
+	p
+		| 直接ユーザーのAPIキーをアプリケーションが扱うのは危険なので、
+		| アプリケーションからAPIを利用する際には、アプリケーションとアプリケーションを利用するユーザーが結び付けられた専用のトークン(アクセストークン)をMisskeyに発行してもらい、
+		| そのトークンをリクエストのパラメータに含める必要があります。
+	div.ui.info: p %fa:info-circle%アクセストークンは、ユーザーが自分のアカウントにあなたのアプリケーションがアクセスすることを許可した場合のみ発行されます
+
+	p それでは、アクセストークンを取得するまでの流れを説明します。
+
+	section
+		h3 1.アプリケーションを登録する
+		p まず、あなたのアプリケーションやWebサービス(以後、あなたのアプリと呼びます)をMisskeyに登録します。
+		p
+			a(href=common.config.dev_url, target="_blank") デベロッパーセンター
+			| にアクセスし、「アプリ > アプリ作成」に進みます。
+			| フォームに必要事項を記入し、アプリを作成してください。フォームの記入欄の説明は以下の通りです:
+
+		table
+			thead
+				tr
+					th 名前
+					th 説明
+			tbody
+				tr
+					td アプリケーション名
+					td あなたのアプリの名称。
+				tr
+					td アプリの概要
+					td あなたのアプリの簡単な説明や紹介。
+				tr
+					td コールバックURL
+					td ユーザーが後述する認証フォームで認証を終えた際にリダイレクトするURLを設定できます。あなたのアプリがWebサービスである場合に有用です。
+				tr
+					td 権限
+					td あなたのアプリが要求する権限。ここで要求した機能だけがAPIからアクセスできます。
+
+		p 登録が済むとあなたのアプリのシークレットキーが入手できます。このシークレットキーは後で使用します。
+		div.ui.info.warn: p %fa:exclamation-triangle%アプリに成りすまされる可能性があるため、極力このシークレットキーは公開しないようにしてください。
+
+	section
+		h3 2.ユーザーに認証させる
+		p あなたのアプリを使ってもらうには、ユーザーにアカウントへのアクセスの許可をもらう必要があります。
+		p
+			| 認証セッションを開始するには、#{common.config.api_url}/auth/session/generate へパラメータに appSecret としてシークレットキーを含めたリクエストを送信します。
+			| リクエスト形式はJSONで、メソッドはPOSTです。
+			| レスポンスとして認証セッションのトークンや認証フォームのURLが取得できるので、認証フォームのURLをブラウザで表示し、ユーザーにフォームを提示してください。
+
+		p
+			| あなたのアプリがコールバックURLを設定している場合、
+			| ユーザーがあなたのアプリの連携を許可すると設定しているコールバックURLに token という名前でセッションのトークンが含まれたクエリを付けてリダイレクトします。
+
+		p
+			| あなたのアプリがコールバックURLを設定していない場合、ユーザーがあなたのアプリの連携を許可したことを(何らかの方法で(たとえばボタンを押させるなど))確認出来るようにしてください。
+
+	section
+		h3 3.ユーザーのアクセストークンを取得する
+		p ユーザーが連携を許可したら、#{common.config.api_url}/auth/session/userkey へ次のパラメータを含むリクエストを送信します:
+		table
+			thead
+				tr
+					th 名前
+					th 型
+					th 説明
+			tbody
+				tr
+					td appSecret
+					td string
+					td あなたのアプリのシークレットキー
+				tr
+					td token
+					td string
+					td セッションのトークン
+		p 上手くいけば、認証したユーザーのアクセストークンがレスポンスとして取得できます。おめでとうございます！
+
+	p アクセストークンが取得できたら、「ユーザーのアクセストークン+あなたのアプリのシークレットキーをsha256したもの」を「i」というパラメータでリクエストに含めると、APIにアクセスすることができます。
+
+	p 「i」パラメータの生成方法を擬似コードで表すと次のようになります:
+	pre: code
+		| const i = sha256(accessToken + secretKey);
+
+	p APIの詳しい使用法は「Misskey APIの利用」セクションをご覧ください。
+
+section
+	h2 Misskey APIの利用
+	p APIはすべてリクエストのパラメータ・レスポンスともにJSON形式です。また、すべてのエンドポイントはPOSTメソッドのみ受け付けます。
+	p APIリファレンスもご確認ください。
+
+	section
+		h3 レートリミット
+		p Misskey APIにはレートリミットがあり、短時間のうちに多数のリクエストを送信すると、一定時間APIを利用することができなくなることがあります。