mirror of
https://codeberg.org/yeentown/barkey
synced 2024-11-25 12:55:14 +00:00
wip
This commit is contained in:
syuilo
parent
5dbdd0e685
commit
608b8bb741
3 changed files with 62 additions and 47 deletions
|
|
@ -72,6 +72,9 @@ export default Vue.extend({
|
|||
},
|
||||
|
||||
parse(md: string) {
|
||||
// 変数置換
|
||||
md = md.replace(/\{_URL_\}/g, url);
|
||||
|
||||
// markdown の全容をパースする
|
||||
const parsed = markdown.parse(md, {});
|
||||
if (parsed.length === 0) return;
|
||||
|
|
|
|||
|
|
@ -1,3 +1,60 @@
|
|||
# Misskey API
|
||||
|
||||
[APIリファレンス](/api-doc)
|
||||
MisskeyAPIを使ってMisskeyクライアント、Misskey連携Webサービス、Bot等(以下「アプリケーション」と呼びます)を開発できます。
|
||||
ストリーミングAPIもあるので、リアルタイム性のあるアプリケーションを作ることも可能です。
|
||||
|
||||
APIを使い始めるには、まずAPIキーを取得する必要があります。
|
||||
このドキュメントでは、APIキーを取得する手順を説明した後、基本的なAPIの使い方を説明します。
|
||||
|
||||
## APIキーの取得
|
||||
基本的に、APIはリクエストにはAPIキーが必要となります。
|
||||
あなたの作ろうとしているアプリケーションが、あなた専用のものなのか、それとも不特定多数の人に使ってもらうものなのかによって、APIキーの取得手順は異なります。
|
||||
|
||||
* あなた専用の場合: [「自分のアカウントのAPIキーを取得する」](#自分のアカウントのAPIキーを取得する)に進む
|
||||
* 皆に使ってもらう場合: [「アプリケーションとしてAPIキーを取得する」](#アプリケーションとしてAPIキーを取得する)に進む
|
||||
|
||||
### 自分のアカウントのAPIキーを取得する
|
||||
「設定 > API」で、自分のAPIキーを取得できます。
|
||||
|
||||
> この方法で入手したAPIキーは強力なので、第三者に教えないでください(アプリなどにも入力しないでください)。
|
||||
|
||||
[「APIの使い方」へ進む](#APIの使い方)
|
||||
|
||||
### アプリケーションとしてAPIキーを取得する
|
||||
アプリケーションを使ってもらうには、ユーザーのAPIキーを以下の手順で取得する必要があります。
|
||||
|
||||
#### Step 1
|
||||
|
||||
UUIDを生成する。以後これをセッションIDと呼びます。
|
||||
|
||||
#### Step 2
|
||||
|
||||
`{_URL_}/miauth/{session}`をユーザーのブラウザで表示させる。`{session}`の部分は、セッションIDに置き換えてください。
|
||||
> 例: `{_URL_}/miauth/c1f6d42b-468b-4fd2-8274-e58abdedef6f`
|
||||
|
||||
表示する際、URLにクエリパラメータとしていくつかのオプションを設定できます:
|
||||
* `name` ... アプリケーション名
|
||||
* > 例: `MissDeck`
|
||||
* `callback` ... 認証が終わった後にリダイレクトするURL
|
||||
* > 例: `https://missdeck.example.com/callback`
|
||||
* リダイレクト時には、`session`というクエリパラメータでセッションIDが付きます
|
||||
* `permissions` ... アプリケーションが要求する権限
|
||||
* > 例: `write:notes,write:following,read:drive`
|
||||
* 要求する権限を`,`で区切って列挙します
|
||||
* どのような権限があるかは[APIリファレンス](/api-doc)で確認できます
|
||||
|
||||
#### Step 3
|
||||
ユーザーが連携を許可した後、`{_URL_}/miauth/{session}/check`にPOSTリクエストすると、レスポンスとしてAPIキーを含むJSONが返ります。
|
||||
|
||||
レスポンスに含まれるプロパティ:
|
||||
* `token` ... ユーザーのAPIキー
|
||||
* `user` ... ユーザーの情報
|
||||
|
||||
[「APIの使い方」へ進む](#APIの使い方)
|
||||
|
||||
## APIの使い方
|
||||
**APIはすべてPOSTで、リクエスト/レスポンスともにJSON形式です。RESTではありません。**
|
||||
APIキーは、`i`というパラメータ名でリクエストに含めます。
|
||||
|
||||
* [APIリファレンス](/api-doc)
|
||||
* [ストリーミングAPI](./stream)
|
||||
|
|
|
|||
|
|
@ -42,52 +42,7 @@ export function getDescription(lang = 'ja-JP'): string {
|
|||
.join('\n');
|
||||
|
||||
const descriptions = {
|
||||
'ja-JP': `**Misskey is a decentralized microblogging platform.**
|
||||
|
||||
# Usage
|
||||
**APIはすべてPOSTでリクエスト/レスポンスともにJSON形式です。**
|
||||
一部のAPIはリクエストに認証情報(APIキー)が必要です。リクエストの際に\`i\`というパラメータでAPIキーを添付してください。
|
||||
|
||||
## 自分のアカウントのAPIキーを取得する
|
||||
「設定 > API」で、自分のAPIキーを取得できます。
|
||||
|
||||
> アカウントを不正利用される可能性があるため、このトークンは第三者に教えないでください(アプリなどにも入力しないでください)。
|
||||
|
||||
## アプリケーションとしてAPIキーを取得する
|
||||
直接ユーザーのAPIキーをアプリケーションが扱うのはセキュリティ上のリスクがあるので、
|
||||
アプリケーションからAPIを利用する際には、アプリケーションとアプリケーションを利用するユーザーが結び付けられた専用のAPIキーを発行します。
|
||||
|
||||
### 1.アプリケーションを登録する
|
||||
まず、あなたのアプリケーションやWebサービス(以後、あなたのアプリと呼びます)をMisskeyに登録します。
|
||||
[デベロッパーセンター](/dev)にアクセスし、「アプリ > アプリ作成」からアプリを作成してください。
|
||||
|
||||
登録が済むとあなたのアプリのシークレットキーが入手できます。このシークレットキーは後で使用します。
|
||||
|
||||
> アプリに成りすまされる可能性があるため、極力このシークレットキーは公開しないようにしてください。</p>
|
||||
|
||||
### 2.ユーザーに認証させる
|
||||
アプリを使ってもらうには、ユーザーにアカウントへのアクセスの許可をもらう必要があります。
|
||||
|
||||
認証セッションを開始するには、[${config.apiUrl}/auth/session/generate](#operation/auth/session/generate) へパラメータに\`appSecret\`としてシークレットキーを含めたリクエストを送信します。
|
||||
レスポンスとして認証セッションのトークンや認証フォームのURLが取得できるので、認証フォームのURLをブラウザで表示し、ユーザーにフォームを提示してください。
|
||||
|
||||
あなたのアプリがコールバックURLを設定している場合、
|
||||
ユーザーがあなたのアプリの連携を許可すると設定しているコールバックURLに\`token\`という名前でセッションのトークンが含まれたクエリを付けてリダイレクトします。
|
||||
|
||||
あなたのアプリがコールバックURLを設定していない場合、ユーザーがあなたのアプリの連携を許可したことを(何らかの方法で(たとえばボタンを押させるなど))確認出来るようにしてください。
|
||||
|
||||
### 3.アクセストークンを取得する
|
||||
ユーザーが連携を許可したら、[${config.apiUrl}/auth/session/userkey](#operation/auth/session/userkey) へリクエストを送信します。
|
||||
|
||||
上手くいけば、認証したユーザーのアクセストークンがレスポンスとして取得できます。おめでとうございます！
|
||||
|
||||
アクセストークンが取得できたら、*「ユーザーのアクセストークン+あなたのアプリのシークレットキーをsha256したもの」*をAPIキーとして、APIにリクエストできます。
|
||||
|
||||
APIキーの生成方法を擬似コードで表すと次のようになります:
|
||||
\`\`\` js
|
||||
const i = sha256(userToken + secretKey);
|
||||
\`\`\`
|
||||
|
||||
'ja-JP': `
|
||||
# Permissions
|
||||
|Permisson (kind)|Description|Endpoints|
|
||||
|:--|:--|:--|
|
||||
|
|
|
|||
Loading…
Reference in a new issue