APIの利用方法

目次

ここでは、Node.js上でHTTPクライアント「axios」を使用し、APIを操作してみる。

ここで提示するコードはRunKitで実際に実行できる。

iを取得する

MisskeyのAPIでは、APIキーとも呼ばれるキーをiとして本文に含めることでAPIを利用できる。
様々な場面でiという名前で扱われるため、ここではこのAPIキーを単にiと呼ぶことにする。

自分のアカウントのiを取得する

自分のアカウントのiは設定のAPIタブ(/i/settings/api)のTokenに表示されている。

ここで取得できる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!」という文章が投稿されたはずだ。

アプリケーションとしてiを取得する

上の方法で取得したiをアプリケーションで使用するのは大変危険なため、アプリケーションからAPIを利用する際には、アプリケーションとユーザーが結び付けられた専用のAPIキーを発行する。

1. アプリケーションの作成

まず、各インスタンスでアプリケーションを登録し、シークレットキーappSecretを取得する。

アプリケーションの登録時にはパーミッションの設定が必要なので、まずは各インスタンスの/api-doc(例: https://misskey.io/api-doc )で必要なパーミッションを確認しよう。

appSecretは、次の2つの方法で取得できる。
ここでは仮にfAb12cD34Ef56gH78Ij16kL32Mn64oPfというappSecretを取得したものとして進める。

開発者センターから作成

各インスタンスのデベロッパーセンター/dev(例: https://misskey.io/dev )でアプリケーションを作成しappSecretを取得する。

APIで取得

app/createエンドポイントを利用することでもアプリケーションを作成できる。

axios.post("https://misskey.io/api/app/create", {
    // アプリの名前
    name: "test",
    // アプリの説明
    description: "my test application",
    // アプリのパーミッション
    permission: ["write:notes"]
}).then(({data}) => console.log(data.secret))

この時、callbackUrlでお好きなURLを含めると、次のアクセス許可操作が終了したときにtokenをクエリ文字列に含めながらそこにコールバックするようになる。

2. ユーザーに認証させる

auth/session/generateエンドポイントにappSecretをPOSTする。

axios.post("https://misskey.io/api/auth/session/generate", {appSecret: "fAb12cD34Ef56gH78Ij16kL32Mn64oPf"})
  .then(({data}) => console.log(data))

token(ここでは仮に798b9f6e-248d-43a7-a919-fabc664027f1)とurlを返してくるので、まずはこのurlにウェブブラウザでアクセスし「アクセスを許可」を選択。

3. accessTokenを問い合わせる

2が終わったことが確認できたら、auth/session/userkeyエンドポイントにappSecretと先ほどのtokenをPOSTする。

axios.post("https://misskey.io/api/auth/session/userkey", {
  appSecret: "fAb12cD34Ef56gH78Ij16kL32Mn64oPf",
  token: "798b9f6e-248d-43a7-a919-fabc664027f1"
}).then(({data}) => console.log(data.accessToken))

ここで取得できる文字列はaccessTokenと呼ばれる。accessTokenは一度限りしか取得できない。

3. iを生成

iは、Node.jsであれば以下のようなコードで生成でき、設定画面で取得するものとは違って64桁の16進数である。

const crypto = require("crypto")
const i = crypto.createHash("sha256")
    .update(accessToken + appSecret, "utf8")
    .digest("hex")
console.log(i)

4. 実際にテストする

axios.post("https://misskey.io/api/notes/create", {
  i: "/* ここにiを入力 */",
  text: "Hello Misskey API World with My Application!"
})

様々なエンドポイントを利用する

各インスタンスの/api-doc(例: https://misskey.io/api-doc )にアクセスすることで、そのインスタンスで利用できるAPIの一覧と必要なパーミッションを見ることができる。

Misskey Webの設定のAPIタブ(/i/settings/api)のAPIコンソールでAPIをテストできる。APIコンソールで実行した内容は実際に反映される。