ウミブドウ APIマニュアル
ウミブドウのAPIは、外部のアプリやツールからAPIキーを使って接続するための仕組みです。このマニュアルでは、APIキーの取得方法と、動作確認用の sayHello、ノートの取得APIの使い方を説明します。
APIキーの取得
- ウミブドウにログインし、設定の詳細にある「APIキー管理」を開きます
- 名前と有効期限を指定して「APIキーを発行」を押します
- 発行されたキー(
umi_で始まる文字列)は、発行時の画面にだけ表示されます。閉じる前にコピーして、安全な場所に保存してください - キーは1ユーザーにつき10件まで発行できます。不要になったキーは一覧から削除してください(削除したキーでは、すぐに接続できなくなります)
APIキーの使い方
APIを呼ぶときは、Authorization ヘッダーに Bearer <キー> の形でキーを付けます。キーをURLやリクエスト本文に含めないでください。
sayHello(動作確認)
APIキーが正しく使えるかを確認するためのAPIです。
- メソッド:
GET - URL:
user_api/say_hello.php - 認証:
Authorization: Bearerヘッダー
呼び出し例(curl):
curl -H "Authorization: Bearer umi_1_xxxxxxxx" https://outline.uta.pw/user_api/say_hello.php
成功すると、次のようなJSONが返ります。
{"ok": true, "message": "Hello, (あなたの表示名)!", "user_id": 1, "display_name": "(あなたの表示名)"}
ノートの一覧を取得する
自分のノートの一覧を取得するAPIです(読み取り専用)。
- メソッド:
GET - URL:
user_api/outlines.php - 認証:
Authorization: Bearerヘッダー - 応答:
{"ok": true, "outlines": [{"id": 1, "name": "ノートの名前", "visibility": "private", "published": false, "created_at": "...", "updated_at": "...", "edited_at": "..."}]}
ノートの内容を取得する
ノートの内容(項目の一覧)を取得するAPIです(読み取り専用)。一覧で取得した id を file_id に指定します。
- メソッド:
GET - URL:
user_api/outline_tree.php?file_id=<id> - 認証:
Authorization: Bearerヘッダー - 応答:
{"ok": true, "file": {"id": 1, "name": "ノートの名前", "...": "..."}, "nodes": [{"id": 1, "parent_id": null, "position": 0, "text": "項目のテキスト", "...": "..."}]} file_idが無い・正の整数でない場合は 400、存在しないノートや他人のノートの場合は 404 が返ります
ノートを作成する
新しいノートを作成するAPIです。作成したノートの file_id を、項目の書き込みにそのまま使えます。
- メソッド:
POST - URL:
user_api/outline_create.php - 認証:
Authorization: Bearerヘッダー - リクエスト:
{"name": "ノートの名前"}(JSONの本文。nameは必須で、120バイトまで) - 応答:
{"ok": true, "file_id": 1, "file": {"id": 1, "name": "ノートの名前", "visibility": "private", "published": false, "created_at": "...", "updated_at": "...", "edited_at": "...", "encryption_version": 0}} - 暗号化ノートとして作る場合は
"encryption_version": 1を追加します(省略時は暗号化なしです)。先に暗号化パスワードを設定していないと 409 が返ります - 画面で開いているノートは変わりません
ノートに書き込む
APIキーでノートの項目を作成・更新・削除することもできます。書き込みは POST で、JSONの本文を送ります(file_id は必須です)。
- 作成:
POST user_api/node_create.phpに{"file_id": 1, "parent_id": null, "position": 0, "text": "新しい項目"}を送ります - 更新:
POST user_api/node_update.phpに{"file_id": 1, "id": 2, "text": "書き換えた項目"}を送ります(idは項目のIDです) - 削除:
POST user_api/node_delete.phpに{"file_id": 1, "id": 2}を送ります
呼び出し例(curl):
curl -X POST -H "Authorization: Bearer umi_1_xxxxxxxx" -H "Content-Type: application/json" -d "{\"file_id\": 1, \"parent_id\": null, \"position\": 0, \"text\": \"新しい項目\"}" https://outline.uta.pw/user_api/node_create.php
APIキーは発行した本人の権限で動くため、キーが漏れるとノートを書き換えられるおそれがあります。書き込みに使わないキーは発行しない、漏れたおそれがあるキーはすぐ削除する、といった管理をお願いします。
エラー
- 400:
file_idが無い、または正の整数でない場合です - 401 Invalid API key: キーが無い、キーが間違っている、期限が切れている、削除済みのキーの、どれかです。理由は区別して返しません
- 404 File not found: ノートが存在しない、または他人のノートの場合です(どちらかは区別して返しません)
- 405 Method not allowed:
GET以外のメソッドで呼んだ場合です
注意
- APIキーは、発行した本人の権限で使われます。キーを他人と共有しないでください
- キーが漏れたおそれがある場合は、APIキー管理からそのキーを削除し、新しいキーを発行してください
- 有効期限を設定したキーは、期限を過ぎると自動的に使えなくなります