主要な概念

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

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

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

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

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

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

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

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

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

APIの使用

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

1. ログイン - 新しいリフレッシュトークンを作成します。
2. アクセストークン - ユーザーにREST APIリソースへのアクセスを許可するために使用します。
3. ログアウト - リフレッシュトークンを削除します。
4. リソースのリクエスト - REST APIを使用して、実際にデータを取得します。

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

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

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

アクセストークン

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

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

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

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');
  
  
  

• Error 500 Internal Server Error - これは、サーバ上で何か問題が発生したことを示す一般的なエラーメッセージです。詳細については、サーバログにあるエラートレースをサポートに連絡してください。

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

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