REST API

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

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

概要

Yellowfinは、一般的なREST APIを公開することで、外部の開発者は独自のユーティリティやアプリケーションを作成したり、Yellowfinのシステムやコンテンツと統合したりすることができます。これは、JS API、SOAP API、完全アプリケーション統合などの既存の統合と並行して、または完全にスタンドアローンの統合ツールとして機能します。

このAPIは、ストーリー、シグナル、ディスカッションストリーム、レポート (近日公開予定) 、ユーザー、ユーザータイムラインなど、いくつかの主要なコンテンツタイプの大部分の機能を公開します。また、ユーザー管理、カテゴリー管理、インポート/エクスポート、システム構成、ユーザーセッション管理などの機能を提供する管理機能も備えているため、開発者は独自のユーティリティを使用して、Yellowfinシステムを管理および制御できます。

このAPIには、次のような用途があります。

シグナルやその他のコンテンツを閲覧したり、表示したりするなど、Yellowfinのコンテンツをサードパーティ製アプリケーション内に統合します。また、コンテンツがどのように表示され、ユーザーがどのように対話し、移動するかを制御することができます。
Web インターフェースにログインすることなく、Yellowfin インスタンスの構成や設定を管理できるサードパーティ製アプリケーションなどの管理ユーティリティを作成します。
Yellowfin アプリケーションユーザーインタフェースの完全にカスタマイズされた実装を構築し、開発者がアプリケーションの表示方法や操作方法を制御したり、ユーザーやその他の特定の要件に基づいて機能を制限したりできるようにします。

主要な概念

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のバージョンを識別するために使用されます。
その形式は、各エンドポイントのAPIドキュメントで指定されています。大部分のリソースはJSON表現を備えているため、例えばv1 JSONリソースは、application/vnd.yellowfin.api-v1+jsonを必要とします。
APIは下位互換性があります。v1リソースのリクエストは、Yellowfin インスタンスの現在のAPIバージョンがv2でも動作します。

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

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

すべてのAPIレスポンスは、ひとつの「_links」オブジェクトを持ちます。「_links」オブジェクトには、ひとつまたは複数のリンクオブジェクトを含めることもできます。

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

一部のAPIレスポンスは「_embedded」オブジェクトを持ちます。このオブジェクトには、現在のリソースに関連する追加の有用な情報を含むサブオブジェクトを含めることができますが、そのリソースには直接属しません。これらは、独自のプロパティとリンクを持つ個別のリソースです。

認証

ページトップ

APIの大部分のエンドポイントでは認証が必要です。主な例外は、次の通りです。

base /apiリソース。これは、apiコンシューマーアプリケーションによって一般的に使用され、基本api情報を取得するために、認証の有無にかかわらず使用できます。
要求された資格情報がリクエストの一部として渡される独自のインライン認証を提供する一部のエンドポイント (より詳細な情報は、REST API ドキュメントを参照してください)。

標準的なログインフローは、リフレッシュトークンの認証と生成のために、サーバーにユーザーの資格情報を渡します。また、利便性のためにアクセストークンも渡します。リフレッシュトークンはその後アクセストークンを作成するために使用し、その他のリソースへのアクセスに使用することができます。

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

HTTP操作はPOSTを使用します。どのようなリソースを作成するリクエストでも、常にPOST操作を使用します。これにより、リフレッシュトークンが作成されます。
リフレッシュトークンエンドポイントの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」リンクも保存します。

シングルサインオン

このAPIは、REST API自体にシングルサインオン (SSO) 機能を提供します。これにより、RESTユーザーは別のRESTユーザーにログオンし、そのユーザーのリフレッシュトークンを生成できます。リフレッシュトークンは、そのユーザー (または、他のアプリケーション) に転送して、APIの使用を許可することができます。このエンドポイントは、SSOリクエストを行っているRESTユーザーのインライン認証をサポートし、単純な認証をサポートします (SSOでのnoPassword SSOエラーについては、下記のトラブルシューティング項目を参照してください)。

オンボーディング

これは基本的に、Web アプリケーションから実行できる別の形式のSSOです。管理者は、特定のユーザー用のオンボーディングトークンを生成して外部アプリケーションに渡すことで、外部アプリケーションは、ユーザーの資格情報を使用してリフレッシュトークンを生成する代わりに、そのトークンを認証フローに渡すことができます。トークンがリフレッシュトークンのPOSTリクエストとともに渡された場合 (これは、上記通常のREST SSOリクエストではありません) 、このトークンは、Web アプリケーションで作成されたトークンと照合され、ユーザーをログオンさせます。

Web SSO

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を使用することです。

HTTPメソッドをPOSTに、URLを/login-tokens/create-sso-tokenに設定します。
必要なヘッダーを設定します。

リクエストボディは、生JSONに設定します。
レスポンスにはログイントークンと、セッションを終了するためのAPI エンドポイントが含まれます。
Yellowfin Web UI、またはJavaScript APIにログインするために、トークンが使用される場合があります。詳細は、こちらを参照してください。

アクセストークン

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

HTTP操作にPOSTを選択します。
アクセストークンエンドポイントのURLを使用します。
リフレッシュトークンリクエストと同様のヘッダーを使用します。
- 認証ヘッダーは、リフレッシュトークンを「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ドキュメントを参照してください。

Base API リソース

このエンドポイントは、標準RESTリソースとして表されるAPI自体の現在の状態を示します。これは、ログインしているユーザーとログインしていないユーザーの両方が使用できるため、アクセストークンの有無にかかわらずアクセスできます。これは、現在のAPIバージョンなどのAPI情報、現在のアプリケーションバージョンなどのサーバ情報を返します (以下の注意を参照してください) 。エンドポイントは、現在のユーザーが使用できるすべての最上位レベルのリソースも返します (ログインしているユーザーがいない場合は、ログインしていないユーザーがアクセスできる最上位のエンドポイントを返します)。

同じRESTバージョンのアプリケーションバージョン間で使用可能なエンドポイントが異なる場合があるため、APIバージョンと同様にこの値に注意することが重要です。

標準リソース

ほとんどすべての標準リソースは、アクセストークン認証を必要とし、大部分はJSONとして表現されます (エンドポイントの詳細については、REST APIドキュメントを参照してください) 。これらは通常、標準構造を共有し、オブジェクトのプロパティ、ナビゲーション用の_linksおよび_embeddedプロパティ、その他の有用な情報を持ちます。

大部分のリストエンドポイントは、JSONでシリアライズされたオブジェクトを使用してエンドポイントにフィルタリング情報を渡すフィルタリングシステムを実装しています。これらのエンドポイントには、通常、現在のユーザーが使用できるフィルター値を示す直接の子/metadata リソースも付随します。各エンドポイントのより詳細な情報については、REST APIドキュメントを参照してください。

APIレスポンスで返されるモデルフィールドを制御できるフィールドパラメーターを提供するエンドポイントがいくつかあります。これらは、含める必要があるプロパティ名のシリアル化されたJSONリストとして送信されます。この機能は、すべてのエンドポイントで均一に実装されているわけではなく、すべてのフィールドをすべてのエンドポイントで除外できるわけではありません。各エンドポイントについて、より詳細な情報は、REST APIのドキュメントを参照してください。

RPC リソース

RPC (Remote Procedure Call: リモートプロシージャコール) エンドポイントは、認証 (一部のRPC エンドポイントはインライン認証を備えています。詳細は、REST API ドキュメント参照) およびレスポンス構造の同じルールに従いますが、REST パラダイムには従わないという点で、標準リソースエンドポイントに類似しています。これらは、リソースを直接表すのではなく、サーバー上で実行されるプロシージャを表します。すべてのRPCエンドポイントは、POST操作を使用します。

これらが存在する理由は、ステートフルな相互作用を必要とするエンドポイントや、複雑なマルチリクエスト呼び出し構造など、RESTパラダイムに適合するのが非常に難しい機能を実装しているからです。これらは通常、既存のSOAPサービスまたはWeb アプリケーションインタフェースから移行された機能であり、明確にリファクタリングすることは非常に困難です。これらの機能の一部は、将来完全なRESTful実装に変換される可能性があります。

リクエストボディパラメーター

ページトップ

使用可能なPOST操作を持つほとんどのエンドポイントは、追加のパラメーターを必要としないほど単純でない限り、リクエストボディにパラメーターを渡す必要があります。必要とされるリクエストボディの形式が異なるのは、主に次2つの状況です。

application/form-dataを必要とするリクエストは、通常、何らかのファイルアップロードを必要とするリクエストです。つまり、ボディはform-dataとして渡され、正しいエンコーディングを使用する必要があります。ファイルアップロードパラメーターを参照しないサブオブジェクトは、form-data内で生のJSONとしてエンコードする必要があります。
ファイルアップロードパラメーターを持たない他のすべてのリクエストは、リクエストボディで生のJSONを使用します。

各エンドポイントの正確な要件については、REST API ドキュメントを参照してください。

ログインフローの例

一般的に、APIのほとんどの使用例では、REST APIへのログインと同様のアプローチに従う必要があります。このアプローチは、REST APIへの初期接続およびユーザーログインを構成します。ユーザーまたは管理者による強制ログアウトによってトークンが無効化されない限り、後続の接続で別のリフレッシュトークンを生成する必要はありません。一部のサーバーより上位の機能をサポートするアプリケーションの場合は、セッション間でサーバーのバージョンが変更されていないことを確認することを推奨します。

APIのバージョンについてサーバーをプローブします。
- これは、base/api エンドポイントにGETリクエストを行うことで実現できます (詳細は、Base API リソース項目を参照してください) 。ここで返される結果は、サーバのAPIバージョンおよびアプリケーションバージョンを決定します。これにより、API使用者は、サーバのサポートされているバージョン範囲内にあるサポートされているバージョンを使用して対話できます。
- base/api エンドポイントは、バージョン1.0と1.1には存在しなかったことに注意してください。バージョン1.0と1.1は本質的に同一であり、ほぼ100%の互換性があります (相違点については、各バージョンのドキュメントを参照してください) 。そのため、このエンドポイントから404応答を受け取ることは、サーバーはこれらのバージョンのいずれかを実行していることを示し、v1にフォールバックすると、v1.1からの非常にマイナーな変更を除いて、すべてのケースで動作することになります。
利用可能ないずれかの方法でリフレッシュトークンを生成します（詳細は、ログイン項目を参照してください）。
リフレッシュトークンレスポンスから自動的に生成されたアクセストークンを使用するか、必要に応じて独自のアクセストークンを作成してください（しばらくアクティビティがなかった場合、生成されたアクセストークンは期限切れになることがあります）。
これで、アクセストークンを使って、この種のトークンを必要とするすべての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');