公開アプリ情報を取得する開発者

公開カタログ API

認証不要の読み取り API について、エンドポイント、レスポンス、エラー、実行例を説明します。

このページの内容

取得できる情報と前提
一覧を取得する
単一のアプリを取得する
主なレスポンス項目
Node.js で取得する
失敗時の扱いと連携上の注意

取得できる情報と前提

公開カタログ API は、公開中のアプリの紹介情報を JSON で取得するための読み取り用エンドポイントです。利用者の履歴、購入情報、非公開の申請、アプリを管理する権限は含みません。

ベース URL は https://sephirothsystem.com です。以下の GET エンドポイントにはログインや API キーは必要ありません。掲載の申請や更新に使う API ではありません。

取得できる情報と前提
メソッド・パス	用途
GET /api/directory/apps	公開アプリの一覧を取得する
GET /api/directory/apps/{slug}	スラッグで指定した公開アプリを取得する

一覧を取得する

GET /api/directory/apps は、apps 配列を含むオブジェクトを返します。公開対象がない場合、配列は空になることがあります。ページ番号、検索語、カテゴリなどのクエリパラメーターによる絞り込みは、現在の公開仕様にはありません。

レスポンスの Cache-Control は no-store です。アプリの公開状況や説明は変わるため、保存した情報を永続的に正しいものとして扱わないでください。必要以上に短い間隔で繰り返し取得しない実装にします。

一覧レスポンスの構造（項目を抜粋）

{
  "apps": [
    {
      "slug": "sephiroth-system",
      "name": "Sephiroth System",
      "homepage": "https://sephirothsystem.com",
      "status": "active",
      "launchMode": "external"
    }
  ]
}

単一のアプリを取得する

一覧から得た slug を URL のパスに指定します。名前から独自にスラッグを推測せず、取得した値を encodeURIComponent などでエンコードして使用してください。

見つかった場合は { "app": ... } を返します。公開対象が見つからない場合は HTTP 404 と { "error": "App not found" } を返します。以前は取得できたアプリでも、公開状況の変更によって取得できなくなる場合があります。

リクエスト例

GET https://sephirothsystem.com/api/directory/apps/sephiroth-system

主なレスポンス項目

以下はアプリ情報の主な項目です。URL や説明文などの任意項目が存在する前提で実装せず、未設定の場合の表示を用意してください。API の説明文は登録された値を返すため、ポータル上で整えた表示文や翻訳と一致しない場合があります。

主なレスポンス項目
項目	型・内容
slug	string。公開アプリを URL 上で識別する値。
name / tagline / description	string。名前、短い説明、詳細説明。
category / tags	分類の文字列と、任意の文字列配列。未知のカテゴリも扱えるようにする。
homepage / launchMode	公式サイトの URL と、外部へ開く方式を示す external。
ownerName	string。公開表示用の運営者名。認証や権限の判定には使わない。
status / displayOrder	公開状態の値と表示順の数値。
iconUrl / screenshotUrls	任意の画像 URL と画像 URL の配列。
supportUrl / termsUrl / privacyUrl	任意のサポート、利用規約、プライバシーポリシーの URL。
commercialDisclosureUrl	任意の特定商取引法に基づく表記の URL。
createdAt / updatedAt	任意の作成・更新時点の情報。未設定を許容する。

Node.js で取得する

次の例は、fetch が使える Node.js 20 以降のサーバー環境で実行できます。ファイルを catalog.mjs として保存し、node catalog.mjs を実行します。キーやログイン情報は不要です。

ブラウザから別のオリジンへ直接アクセスする場合は CORS の制約を受けます。クロスオリジンのブラウザ呼び出しを保証する仕様ではないため、連携先のサーバーから取得する構成で検討してください。

catalog.mjs

const baseUrl = 'https://sephirothsystem.com';

const response = await fetch(`${baseUrl}/api/directory/apps`, {
  signal: AbortSignal.timeout(10_000),
});
if (!response.ok) {
  throw new Error(`Catalog request failed: ${response.status}`);
}
const { apps } = await response.json();
for (const app of apps) {
  console.log(app.name, app.homepage);
}

if (apps.length > 0) {
  const slug = encodeURIComponent(apps[0].slug);
  const detail = await fetch(`${baseUrl}/api/directory/apps/${slug}`, {
    signal: AbortSignal.timeout(10_000),
  });
  if (detail.status === 404) {
    console.log('The app is no longer available in the catalog.');
  } else if (!detail.ok) {
    throw new Error(`Detail request failed: ${detail.status}`);
  } else {
    console.log((await detail.json()).app);
  }
}

失敗時の扱いと連携上の注意

HTTP ステータスを確認してから成功レスポンスを読み取ります。タイムアウトや一時的なサーバー障害は、上限を設けた待機付きの再試行として扱い、404 は同じ URL への即時再試行を繰り返さず公開状態を見直します。

外部から取得した文字列や URL は、そのまま HTML として埋め込まず適切に扱ってください。公開カタログは紹介情報であり、ユーザーの本人確認や開発者権限、支払いの成功判定には使用できません。

実際の一覧レスポンスを開く