Published — v. 17
/
REST API

REST API

Owned by YUKA SAITO
Last updated: Jan 08, 2025

現在利用可能な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」と記述する必要があります。

ts1970年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」オブジェクトを持ちます。このオブジェクトには、現在のリソースに関連する追加の有用な情報を含むサブオブジェクトを含めることができますが、そのリソースには直接属しません。これらは、独自のプロパティとリンクを持つ個別のリソースです。


認証