APIの利用方法
ここでは、Node.js上でHTTPクライアント「axios」を使用し、APIを操作してみる。
ここで提示するコードはRunKitで実際に実行できる。
公式ドキュメント: https://github.com/syuilo/misskey/blob/develop/src/docs/api.ja-JP.md
iを取得する
MisskeyのAPIでは、APIキーとも呼ばれるキーをi
として本文に含めることでAPIを利用できる。
様々な場面でi
という名前で扱われるため、ここではこのAPIキーを単にi
と呼ぶことにする。
自分のアカウントのiを取得する
自分のアカウントのiはアカウント設定(/my/settings
)のAPI欄のトークンに表示されている。
ここで取得できるiは特別なiで、アカウントの全ての情報を操作できるため、インターネット上に公開したり第三者に教えたりしてはいけない。
まずはこのiを使って実際にAPIから投稿してみよう。
次のコードを、1248aBCDeFGH1632
を自分のi
に書き換えて実行してみよう。自分が登録しているインスタンスがmisskey.ioでない場合は自分のインスタンスのURLに置き換えて実行しよう。
axios.post("https://misskey.io/api/notes/create", {i: "1248aBCDeFGH1632", text: "Hello Misskey API World!"})
.then(({data}) => console.log(data))
自分のアカウントから「Hello Misskey API World!」という文章が投稿されたはずだ。
MiAuthでiを取得する
上の方法で取得したiはアカウントの全ての情報を操作できるため、アプリケーションで使用するのは大変危険である。
WebViewのストレージからiを取得する等の実装は、絶対にしないこと。
アプリケーションからAPIを利用する際には、アプリケーションとユーザーが結び付けられた専用のアクセストークンを発行する。
12.27.0以降で利用できる方式はMiAuthと呼ばれ、今後はこの方式を使うことが推奨される。
MiAuthに対応しているかどうかはapi/meta
のfeatures.miauth
が存在するかどうかで判定できる。
12.27.0未満のバージョンのアクセストークン取得方法はこちら
なお、OAuthでの認証はMisskeyに実装されていない。
1: セッションIDの生成
UUIDを生成する。 以後これをセッションIDと呼ぶ。
このセッションIDは毎回生成し、使いまわさないように。
const { v4 } = require("uuid")
console.log(v4())
// ここでは 19bbf45d-5ae7-4c87-b33e-2933b3eec683 が生成されたものとして進める。
// 実際のインスタンスで試すときは絶対に他のuuidを使うこと。
リンク: UUID生成ツール
2: ユーザーを/miauth/:sessionId
にアクセスさせる
/miauth/19bbf45d-5ae7-4c87-b33e-2933b3eec683
(19bbf...
は生成したセッションIDに置き換える)をユーザーにブラウザでアクセスさせる。
表示する際、URLにクエリパラメータとしていくつかのオプションを設定できる:
name
: アプリケーション名- 例:
MissDeck
- 例:
icon
: アプリケーションのアイコン画像URL- 例:
https://missdeck.example.com/icon.png
- 例:
callback
: 認証が終わった後にリダイレクトするURL- 例:
https://missdeck.example.com/callback
https://missdeck.example.com/callback?session=19bbf45d-5ae7-4c87-b33e-2933b3eec683
というように、クエリパラメータでsession
にセッションIDが設定されてリダイレクトされる。
- 例:
permission
... アプリケーションが要求する権限- 例:
write:notes,write:following,read:drive
- 要求する権限を
,
で区切って列挙する。 - どのような権限があるかは各インスタンスのAPIリファレンス(/api-doc)で確認できる。
- 例:
例:
インスタンスmisskey.example.com
で認証させるとき、以下のURLにユーザーを誘導すればよい。
https://misskey.example.com/miauth/19bbf45d-5ae7-4c87-b33e-2933b3eec683?name=MissDeck&icon=https%3A%2F%2Fmissdeck.example.com%2Ficon.png&callback=https%3A%2F%2Fmissdeck.example.com%2Fcallback&permission=write%3Anotes,write%3Afollowing,read%3Adrive
3: アクセストークンを取得
ユーザーが連携を許可した後、/api/miauth/19bbf45d-5ae7-4c87-b33e-2933b3eec683/check
(19bbf...
は自分のセッションIDに置き換える)にPOSTすると、レスポンスとしてアクセストークンを含むJSONが返る。
レスポンスに含まれるプロパティ:
token
: i(アクセストークン)user
: ユーザーの情報
axios.post("https://misskey.example.com/api/miauth/19bbf45d-5ae7-4c87-b33e-2933b3eec683/check")
.then(({token}) => console.log(token))
様々なエンドポイントを利用する
各インスタンスの/api-doc
(例: https://misskey.io/api-doc )にアクセスすることで、そのインスタンスで利用できるAPIの一覧と必要なパーミッションを見ることができる。
ラッパーライブラリを利用する
有志の方々がAPIをより簡単に利用できるようにするラッパーライブラリを各言語・実行環境向けに開発している。
ライブラリ
サービスにMisskeyアカウントでログインできるようにするには?
MiAuthでは、アプリという概念がないため、「サービスにMisskeyアカウントでログインする」という実装では使い捨てのアクセストークンを発行することになる。
すると、ユーザーの「インストールされたアプリ」に同一のアプリがインストールされるたびに増えていくことになってしまう。
旧来のアプリ型認証を利用するという手段もあるが、この方式は将来的に廃止されるかもしれない。
そこで、joinmisskeyとしては、ActivityPub経由のアカウント確認をお勧めしたい。
ActivityPubで実装することで、MisskeyだけでなくPleromaやMastodonでもアカウント確認が行えるため、より多くのユーザーの認証に対応できることになる。
例として、notestockはActivityPub経由のアカウント確認を実装している。
notestockのActivityPub経由のアカウント確認の手順
- ユーザーに(@username@instance.domainのような)ユーザーネームを入力させ、サーバーに記録する。
- 1.を受け取ったサーバーは乱数を生成し、フロントエンドに伝える。
- ユーザーに、サービスの代表Actorに向けて乱数をメンションさせる。
Misskeyでは、/share?text=(URLエンコードされた任意の文章)
というようなURLにアクセスすると任意の文章が入力された投稿フォームを開くことができるため、このリンクを用意すると良いだろう。 - ユーザーからのメンションを受け取ったら、1で入力させたユーザーネーム及び乱数が合致しているを確認する。これでユーザーの確認はとれた。
- サービスのアクセストークンなどを発行し、4.が終わったことをフロントエンドに伝える。
フロントエンドがユーザーの確認を待つときに、notestockはポーリングで実装しているようだが、Server-Sent Eventsで実装するのもよいだろう。