Update doc

This commit is contained in:
syuilo 2019-02-23 15:35:26 +09:00
parent 140c78e5a7
commit 78a69e3da8
No known key found for this signature in database
GPG key ID: BDC4C49D06AB9D69
2 changed files with 66 additions and 79 deletions

View file

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

View file

@ -267,6 +267,65 @@ const schemas = {
} }
}; };
const desc = `
## Usage
APIはすべてPOSTでリクエスト/JSON形式です
APIは認証情報()\`i\`というパラメータでアクセストークンを添付してください。
###
####
> API
> ()
###
APIを利用する際にはMisskeyに発行してもらいます
#### 1.
Webサービス()Misskeyに登録します
[](/dev) >
:
| | |
|---|---|
| | |
| | |
| URL | URLを設定できますWebサービスである場合に有用です |
| | APIからアクセスできます |
使
> </p>
#### 2.
使
%API_URL%/auth/session/generate appSecret
JSONでPOSTです
URLが取得できるのでURLをブラウザで表示し
URLを設定している場合
URLに token
URLを設定していない場合(())
#### 3.
%API_URL%/auth/session/userkey :
| | | |
|---|---|---|
| appSecret | string | |
| token | string | |
+sha256したものAPIにリクエストできます
:
<pre><code>const i = sha256(userToken + secretKey);</code></pre>
`;
export function genOpenapiSpec(lang = 'ja-JP') { export function genOpenapiSpec(lang = 'ja-JP') {
const spec = { const spec = {
openapi: '3.0.0', openapi: '3.0.0',
@ -274,10 +333,15 @@ export function genOpenapiSpec(lang = 'ja-JP') {
info: { info: {
version: 'v1', version: 'v1',
title: 'Misskey API', title: 'Misskey API',
description: 'Misskey is a decentralized microblogging platform.', description: '**Misskey is a decentralized microblogging platform.**\n\n' + desc,
'x-logo': { url: '/assets/api-doc.png' } 'x-logo': { url: '/assets/api-doc.png' }
}, },
externalDocs: {
description: 'Repository',
url: 'https://github.com/syuilo/misskey'
},
servers: [{ servers: [{
url: config.api_url url: config.api_url
}], }],