REST API

現在利用可能なREST サービスの詳細については、開発者サイトをご確認ください。

注意：Yellowfin 本社の提供するサイト（英語）へリンクします。

主要な概念

REST APIは、/api ネームスペース配下で利用できます。例：https://yellowfin.myapp.com/api/stories

このスイートには、/api/rpc ネームスペースにある、RPCの呼び出しも含まれます。

すべてのAPIリクエストには、認証ヘッダーが必要です。形式は、以下の通りです。

YELLOWFIN ts=1600224140615 nonce=3370ddc4-37d9-41b9-9f24-ada181fdc4bf token=securityToken

要素	説明
YELLOWFIN	カスタム認証スキーマ
ts	1970年1月1日午前0時0分0秒（UTC）であるUNIXエポックからのミリ秒単位時刻です。これは、APIを呼び出すプログラムの現在時刻です。すべてのプログラミング言語には、この形式で現在時刻を取得する方法があります。
nonce	クライアントにより生成されるランダムUUID
token	ユーザーを認証し、リソースへのアクセスを許可するために使用されるセキュリティトークン

すべてのAPIリクエストには、Accept ヘッダーが必要です。

このヘッダーは、APIのバージョンを識別するために使用されます。
その形式は、各endpointのAPIドキュメントで指定されています。通常は次の通りです。application/vnd.yellowfin.api-v1+json
APIは下位互換性があります。v1リソースのリクエストは、Yellowfin インスタンスの現在のAPIバージョンがv2でも動作します。

APIを利用するためのキーとなるセキュリティトークンが2つあります。

トークン	説明
リフレッシュ	これは、ログイン時に取得される不透明なセキュリティトークンです。リフレッシュトークンは有効期限がなく、アクセストークンを取得するためクライアントアプリケーションに安全に保存される場合があります。
アクセス	これはJSON Web Token (JWT)で、20分で有効期限が切れます。アクセストークンは、ほぼすべてのAPIリクエストの認証ヘッダーで送信される必要があります。有効期限が切れると、クライアントアプリケーションは、リフレッシュトークンを使用して、新しいアクセストークンを取得することができます。

すべてのAPIリソースは、ひとつ以上の「_links」オブジェクトを持ちます。

すべてのリンクは、ユーザーがアクセスできる関連リソースを表します。
クライアントは、アプリケーションコードでハードコーディングするのではなく、href属性のリンクを使用して、リソースにアクセスします。
「options」配列は、ユーザーがリンクの使用を許可されているHTTPメソッドを示します。例えば、下の例では、ユーザーはコメントリストを読むことができる（GET）、または新しいコメントを作成できる（POST）ことを示しています。すべてのコメントを削除することはできないため、「comments」リンクでDELETEを利用できません。

APIの使用

REST APIの呼び出しは、以下のカテゴリーにグループ化されることがあります。

ログイン（リフレッシュトークンの作成）

セッションではなく、リフレッシュトークンを使用してユーザーを識別します。使用者は、他のREST endpointを使用する前に、リフレッシュトークンを作成して、アクセストークンを取得する必要があります。リフレッシュトークンの作成は、ログインプロセスと考えることができます。

HTTP操作はPOSTを使用します。どのようなリソースを作成するリクエストでも、常にPOST操作を使用します。これにより、リフレッシュトークンが作成されます。
リフレッシュトークンendpointのURLを使用します。有効なURLは常に名前（例：http://yellowfin.myapp.com/api/...）または、IPアドレス（例：http://127.0.0.1/api/…)のいずれかを持ちます。ポートが指定されている場合もあります（http://yellowfin.myapp.com:8080/api/...）。
必須のリクエストヘッダーをいくつか設定する必要があります。APIリクエストを行うために必要なヘッダーの完全な一覧については、こちらを参照してください。
リクエスト本文には、ユーザー名とパスワードのJSON表現が含まれます。本文が生JSONとして送信されていることを確認してください。

このリクエストの応答には、新しく作成されたリフレッシュトークンと、_embedded プロパティ配下にあるアクセストークンが含まれます。

クライアントアプリケーションは、これらのトークンを安全に保存しなくてはいけません。ログアウトに必要になるため、「self」リンクも保存します。

アクセストークン

アクセストークンの作成は、リフレッシュトークン作成のプロセスとほぼ同じです。作成時には、以下を確認します。

HTTP操作にPOSTを選択します。
アクセストークンendpointのURLを使用します。
リフレッシュトークンリクエストと同様のヘッダーを使用します。
- 認証ヘッダーは、リフレッシュトークンを「token」という名前のプロパティで指定しなくてはいけません。

リフレッシュトークンの応答はアクセストークンを提供し、ログイン後にAPIの利用を開始しやすくします。

ログアウト（リフレッシュトークンの削除）

POST /refresh-tokens リクエストの応答には、REST APIから効果的に「ログアウト」するために必要な情報、つまりリフレッシュトークンを削除するために必要な情報が含まれています。POST /refresh-tokens リクエストの応答には、_links プロパティが含まれています。

「self」リンクのオプション配列には、新しいリフレッシュトークンで実行できる操作が表示されます。DELETEはひとつだけ必要です。DELETE /refresh-tokensを呼び出すと、REST APIから効果的にユーザーをログアウトさせます。

この操作を実行するには、有効なアクセストークンが必要です。これは、認証ヘッダーのtokenプロパティに含まれていなくてはいけません。

リソースのリクエスト

リソースのリクエストをするには、API クライアントに有効なアクセストークンが必要です。各endpointに指定する必要のあるヘッダー、必須およびオプションパラメーターについては、APIドキュメントを参照してください。

Web SSO

APIの一般的な使用例は、Web SSOです。ログイントークンの生成には、2つのAPI endpointを使用できます。生成されたトークンを使用して、Yellowfinのブラウザインターフェースにログインできます。これを行う最も簡単な方法は、RPC endpoint POST / longin-tokens/create-sso-tokenを使用することです。

HTTPメソッドをPOSTに、URLを/login-tokens/create-sso-tokenに設定します。
必要なヘッダーを設定します。
リクエスト本文は、生JSONに設定します。
応答にはログイントークンと、セッションを終了するためのAPI endpointが含まれます。
Yellowfin Web UI、またはJavaScript APIにログインするために、トークンが使用される場合があります。詳細は、こちらを参照してください。

トラブルシューティング

クロックスキュー - 最も一般的に発生するエラーのひとつです。これは、認証ヘッダーのタイムスタンプが、サーバ時刻と同期していないために発生します。±5分の許容値がありますが、この範囲を外れると、APIはエラーで応答します。
トークンの有効期限切れ - 有効期限の切れたアクセストークンを使用すると、APIはエラーで応答します。
認証の失敗 - 無効なユーザー名、またはパスワードを使用すると発生します。
不明なバージョン - Accept ヘッダーに誤ったAPIバージョンを指定すると発生します。
ライセンスエラー - GET /stories/uuidのようなコンテンツサービスは、サーバライセンスが存在する場合のみ利用できます。そうではない場合、APIは401 Unauthorized errorを返します。
CORS - CORSはブラウザにのみ適用されるため、一般的にREST APIにとって問題にはなりません。トークンの安全な保存が容易ではないため、Webブラウザは推奨されるREST クライアントではありません。
SSO エラー - 資格情報とOrg Referenceが正しいことを確認します。noPassword認証を使用している場合は、サーバ側で有効になっていることを確認します。これは、システム構成テーブルにレコードを挿入し、Yellowfinを再起動することで実行します。

INSERT INTO Configuration values (1, 'SYSTEM', 'SIMPLE_AUTHENTICATION', 'TRUE');