現在利用可能なREST サービスの詳細については、開発者サイトをご確認ください。 注意：Yellowfin 本社の提供するサイト（英語）へリンクします。 |
Yellowfinは、一般的なREST APIを公開することで、外部の開発者は独自のユーティリティやアプリケーションを作成したり、Yellowfinのシステムやコンテンツと統合したりすることができます。これは、JS API、SOAP API、完全アプリケーション統合などの既存の統合と並行して、または完全にスタンドアローンの統合ツールとして機能します。
このAPIは、ストーリー、シグナル、ディスカッションストリーム、レポート (近日公開予定) 、ユーザー、ユーザータイムラインなど、いくつかの主要なコンテンツタイプの大部分の機能を公開します。また、ユーザー管理、カテゴリー管理、インポート/エクスポート、システム構成、ユーザーセッション管理などの機能を提供する管理機能も備えているため、開発者は独自のユーティリティを使用して、Yellowfinシステムを管理および制御できます。
このAPIには、次のような用途があります。
REST APIは、/api ネームスペース配下で利用できます。例：https://yellowfin.myapp.com/api/stories
さらに、このスイートにはRPC (Remote Procedure Call: リモートプロシージャコール) エンドポイントが含まれており、RESTパラダイムに適合するのが難しいワークフローをサポートします。これらは、/api/rpc ネームスペースに配置されています。
すべてのAPIリクエストには、認証ヘッダーが必要です。形式は、以下の通りです。
YELLOWFIN ts=1600224140615 nonce=3370ddc4-37d9-41b9-9f24-ada181fdc4bf token=securityToken
| 要素 | 説明 |
| YELLOWFIN | カスタム認証スキーマ このテキストは、アプリケーション名と一致する必要があります。これは、カスタムインストーラープロパティファイル、またはYellowfin構成データベースを使用して設定できます。 注意：テキストはスペースを入れずに大文字で記述する必要があります。例えば、アプリケーション名が「YELLOWFIN」ではなく「BigFishReporting」の場合、認証スキーマは「BIGFISHREPORTING」と記述する必要があります。 |
| ts | 1970年1月1日午前0時0分0秒（UTC）であるUNIXエポックからのミリ秒単位時刻です。これは、APIを呼び出すプログラムの現在時刻です。すべてのプログラミング言語には、この形式で現在時刻を取得する方法があります。 |
| nonce | クライアントにより生成されるランダムUUID |
| token | ユーザーを認証し、リソースへのアクセスを許可するために使用されるセキュリティトークン。 一部のエンドポイントは認証なしでアクセスできるため、すべてのエンドポイントがこの項目を必要とするわけではありません (詳細はこちらを参照してください)。 |
すべてのAPIリクエストには、Accept ヘッダーが必要です。
APIを利用するためのキーとなるセキュリティトークンが2つあります。
| トークン | 説明 |
| リフレッシュ | これは、ログイン時に取得される不透明なセキュリティトークンです。リフレッシュトークンは有効期限がなく、アクセストークンを取得するためクライアントアプリケーションに安全に保存される場合があります。 |
| アクセス | これはJSON Web Token (JWT)で、20分で有効期限が切れます。アクセストークンは、ほぼすべてのAPIリクエストの認証ヘッダーで送信される必要があります。有効期限が切れると、クライアントアプリケーションは、リフレッシュトークンを使用して、新しいアクセストークンを取得することができます。 |
すべてのAPIレスポンスは、ひとつの「_links」オブジェクトを持ちます。「_links」オブジェクトには、ひとつまたは複数のリンクオブジェクトを含めることもできます。
一部のAPIレスポンスは「_embedded」オブジェクトを持ちます。このオブジェクトには、現在のリソースに関連する追加の有用な情報を含むサブオブジェクトを含めることができますが、そのリソースには直接属しません。これらは、独自のプロパティとリンクを持つ個別のリソースです。
APIの大部分のエンドポイントでは認証が必要です。主な例外は、次の通りです。
REST APIは、リフレッシュトークンおよびアクセストークンを使用して、リソースへのアクセスを認証および許可します。これらのトークンは、いくつかの異なる方法で生成することができます。
標準的なログインフローは、リフレッシュトークンの認証と生成のために、サーバーにユーザーの資格情報を渡します。また、利便性のためにアクセストークンも渡します。リフレッシュトークンはその後アクセストークンを作成するために使用し、その他のリソースへのアクセスに使用することができます。
セッションではなく、リフレッシュトークンを使用してユーザーを識別します。使用者は、他のREST エンドポイントを使用する前に、リフレッシュトークンを作成して、アクセストークンを取得する必要があります。リフレッシュトークンの作成は、ログインプロセスと考えることができます。
クライアントアプリケーションは、これらのトークンを安全に保存しなくてはいけません。ログアウトに必要になるため、「self」リンクも保存します。 |
このAPIは、REST API自体にシングルサインオン (SSO) 機能を提供します。これにより、RESTユーザーは別のRESTユーザーにログオンし、そのユーザーのリフレッシュトークンを生成できます。リフレッシュトークンは、そのユーザー (または、他のアプリケーション) に転送して、APIの使用を許可することができます。このエンドポイントは、SSOリクエストを行っているRESTユーザーのインライン認証をサポートし、単純な認証をサポートします (SSOでのnoPassword SSOエラーについては、下記のトラブルシューティング項目を参照してください)。
これは基本的に、Web アプリケーションから実行できる別の形式のSSOです。管理者は、特定のユーザー用のオンボーディングトークンを生成して外部アプリケーションに渡すことで、外部アプリケーションは、ユーザーの資格情報を使用してリフレッシュトークンを生成する代わりに、そのトークンを認証フローに渡すことができます。トークンがリフレッシュトークンのPOSTリクエストとともに渡された場合 (これは、上記通常のREST SSOリクエストではありません) 、このトークンは、Web アプリケーションで作成されたトークンと照合され、ユーザーをログオンさせます。
Web アプリケーションとJavaScript APIの両方で、シングルサインオンを処理するために異なるトークンシステムを使用します。つまり、これらのトークンを相互に使用することはできません。幸いなことに、REST APIには、必要なWeb SSOトークン (REST APIではログイントークンと呼ばれます) を生成する方法がいくつか用意されています。これらのトークンを生成する主な方法は、以下の3つです。
| 生成方法 | 説明 |
| ログイン中に他のユーザーのトークンを生成する | リクエスト内で/login-tokensにユーザーの資格情報を渡すと、そのユーザーが認証され、そのユーザーのWeb SSOトークンが作成されます。これは、管理者アカウントが他の管理者以外のユーザーにログオンするために使用できます。 |
| 現在ログインしているRESTユーザーのトークンを生成する | これは上記と同じフローを使用しますが、セカンダリーユーザーの資格情報が渡されない場合は、代わりに現在のユーザー用のトークンが生成されます。これは、現在のユーザをJS APIやWeb コンテンツにリダイレクトする統合に役立ちます。 |
| ログインしていないときに他のユーザーのトークンを生成する | /rpc/login-tokens エンドポイントを使用することで、インライン認証を使用して、管理ユーザーの資格情報だけではなく、ログインするユーザーの資格情報も渡すことができます。 |
APIの一般的な使用例は、Web SSOです。ログイントークンの生成には、2つのAPI エンドポイントを使用できます。生成されたトークンを使用して、Yellowfinのブラウザインターフェースにログインできます。これを行う最も簡単な方法は、RPC エンドポイント POST / longin-tokens/create-sso-tokenを使用することです。
アクセストークンの作成は、リフレッシュトークン作成のプロセスとほぼ同じです。作成時には、以下を確認します。
リフレッシュトークンのレスポンスはアクセストークンを提供し、ログイン後にAPIの利用を開始しやすくします。
リフレッシュトークンが生成されるログオンフローも、同じ方法でログアウトできます。シングルログオフ (SLO: Single Log-off) は、現在ログインしているユーザーにその権限がある限り、/refresh-tokens エンドポイントによって削除される別のユーザーのトークンIDを渡すことで実現できます。
また、(ログイントークンの作成時に返される) トークンIDを、/login-tokens DELETE エンドポイントに渡すことによって、Web SSOセッションをSLOすることもできます。同じアクセス制限が適用されます。
POST/refresh-tokens リクエストのレスポンスには、REST APIから効果的に「ログアウト」するために必要な情報、つまりリフレッシュトークンを削除するために必要な情報が含まれています。POST/refresh-tokens リクエストのレスポンスには、_links プロパティが含まれています。
「self」リンクのオプション配列には、新しいリフレッシュトークンで実行できる操作が表示されます。DELETEのみが表示されるはずです。DELETE/refresh-tokensを呼び出すと、REST APIから効果的にユーザーをログアウトさせます。
この操作を実行するには、有効なアクセストークンが必要です。これは、認証ヘッダーのtokenプロパティに含まれていなくてはいけません。
各エンドポイントに指定する必要のあるヘッダー、必須およびオプションパラメーターについては、APIドキュメントを参照してください。
このエンドポイントは、標準RESTリソースとして表されるAPI自体の現在の状態を示します。これは、ログインしているユーザーとログインしていないユーザーの両方が使用できるため、アクセストークンの有無にかかわらずアクセスできます。これは、現在のAPIバージョンなどのAPI情報、現在のアプリケーションバージョンなどのサーバ情報を返します (以下の注意を参照してください) 。エンドポイントは、現在のユーザーが使用できるすべての最上位レベルのリソースも返します (ログインしているユーザーがいない場合は、ログインしていないユーザーがアクセスできる最上位のエンドポイントを返します)。
同じRESTバージョンのアプリケーションバージョン間で使用可能なエンドポイントが異なる場合があるため、APIバージョンと同様にこの値に注意することが重要です。 |
ほとんどすべての標準リソースは、アクセストークン認証を必要とし、大部分はJSONとして表現されます (エンドポイントの詳細については、REST APIドキュメントを参照してください) 。これらは通常、標準構造を共有し、オブジェクトのプロパティ、ナビゲーション用の_linksおよび_embeddedプロパティ、その他の有用な情報を持ちます。
大部分のリストエンドポイントは、JSONでシリアライズされたオブジェクトを使用してエンドポイントにフィルタリング情報を渡すフィルタリングシステムを実装しています。これらのエンドポイントには、通常、現在のユーザーが使用できるフィルター値を示す直接の子/metadata リソースも付随します。各エンドポイントのより詳細な情報については、REST APIドキュメントを参照してください。
APIレスポンスで返されるモデルフィールドを制御できるフィールドパラメーターを提供するエンドポイントがいくつかあります。これらは、含める必要があるプロパティ名のシリアル化されたJSONリストとして送信されます。この機能は、すべてのエンドポイントで均一に実装されているわけではなく、すべてのフィールドをすべてのエンドポイントで除外できるわけではありません。各エンドポイントについて、より詳細な情報は、REST APIのドキュメントを参照してください。
RPC (Remote Procedure Call: リモートプロシージャコール) エンドポイントは、認証 (一部のRPC エンドポイントはインライン認証を備えています。詳細は、REST API ドキュメント参照) およびレスポンス構造の同じルールに従いますが、REST パラダイムには従わないという点で、標準リソースエンドポイントに類似しています。これらは、リソースを直接表すのではなく、サーバー上で実行されるプロシージャを表します。すべてのRPCエンドポイントは、POST操作を使用します。
これらが存在する理由は、ステートフルな相互作用を必要とするエンドポイントや、複雑なマルチリクエスト呼び出し構造など、RESTパラダイムに適合するのが非常に難しい機能を実装しているからです。これらは通常、既存のSOAPサービスまたはWeb アプリケーションインタフェースから移行された機能であり、明確にリファクタリングすることは非常に困難です。これらの機能の一部は、将来完全なRESTful実装に変換される可能性があります。
使用可能なPOST操作を持つほとんどのエンドポイントは、追加のパラメーターを必要としないほど単純でない限り、リクエストボディにパラメーターを渡す必要があります。必要とされるリクエストボディの形式が異なるのは、主に次2つの状況です。
各エンドポイントの正確な要件については、REST API ドキュメントを参照してください。
一般的に、APIのほとんどの使用例では、REST APIへのログインと同様のアプローチに従う必要があります。このアプローチは、REST APIへの初期接続およびユーザーログインを構成します。ユーザーまたは管理者による強制ログアウトによってトークンが無効化されない限り、後続の接続で別のリフレッシュトークンを生成する必要はありません。一部のサーバーより上位の機能をサポートするアプリケーションの場合は、セッション間でサーバーのバージョンが変更されていないことを確認することを推奨します。
現在利用可能なREST サービスの詳細については、開発者サイトをご確認ください。
注意：Yellowfin 本社の提供するサイト（英語）へリンクします。