S.Models API 解説：3Dモデルデータを共有するプラットフォームAPIの全貌

この記事では、複数のアプリケーション間で3Dモデルデータを効率的に共有するための S.Models API（旧 3DSS-API / 3D Shape Share API） について解説します。API 設計の考え方から実装方法まで、開発者向けに包括的にお伝えします。

S.Models API とは何か、なぜ必要なのか

現代のアプリケーション開発において、データの一元管理と共有は重要な課題です。特に3Dモデルのような複雑なデータを扱う場合、複数のアプリケーション間で整合性を保ちながら効率的に共有する仕組みが必要になります。

S.Models API は、この課題を解決するために設計されたプラットフォーム API です。Firebase Cloud Functions 上に構築され、Firestore に保存された3Dモデルのメタ情報を JSON 形式で提供します。

主なメリット：

• 複数アプリケーション間でのデータ整合性の確保
• 3Dモデルデータの一元管理
• 開発効率の向上とコードの重複排除
• スケーラブルなデータアクセス基盤の提供

API の概要

技術スタック

• Firebase プロジェクト： shapeshare3d（本番の S.Models と同一）
• 実行環境： Cloud Functions + Express
• データベース： Firestore

Base URL

https://us-central1-shapeshare3d.cloudfunctions.net/api

現在の主要エンドポイント

• GET /models/v1 — モデル一覧取得（limit：任意、デフォルト 10）
• GET /models/v1/:id — 単一モデル取得（id：必須）

S.Models の Firestore に保存されているモデル情報を JSON で返す「窓口」として機能します。将来的には /users/v1、/boards/v1、/articles/v1 なども追加予定です。

プラットフォーム設計の考え方

S.Models API はプラットフォーム層とアプリ層の2層構造で設計されています。この設計により、効率的なデータ共有とアプリケーション間の疎結合を実現しています。

• アプリ層： 各アプリケーション（プレゼン、シミュレーション等）。それぞれ独自の DB を持ってもよい
• プラットフォーム層： S.Models API（共通データへのアクセス窓口）。3Dモデル・ユーザー・ボード・共通タグなどを管理

データ共有の原則

1. ID のみを保持： modelId、userId、boardId 等の参照 ID のみを保存
2. 詳細データは API 経由： 実際のデータは S.Models API から動的に取得
3. 共通データの一元管理： 3Dモデル等の共通リソースはプラットフォーム層で管理

このアプローチにより、どのアプリからも同じ Base URL で共通3Dデータにアクセスでき、整合性が保たれ、アプリ間連携が容易になり、データ更新時の影響範囲を最小化できます。

レスポンス形式

API レスポンスに含まれる主要フィールドは以下の通りです。

• id — モデルの一意識別子（string）
• slug — URL 用識別子（string）
• title — モデル名（string）
• thumbnailUrl — サムネイル URL（string）
• category — カテゴリパス（string）
• modelFormats — 提供フォーマット（array）
• dimensions — サイズ情報（object）
• tags — 関連タグ（array）

レスポンス例

{
  "items": [
    {
      "id": "0052b495-4cf6-42be-b597-ea83340a86c9",
      "slug": "0052b495-4cf6-42be-b597-ea83340a86c9",
      "title": "ハンギングポット",
      "thumbnailUrl": "https://firebasestorage.googleapis.com/...",
      "category": "lighting/pendant",
      "modelFormats": [],
      "dimensions": null,
      "tags": []
    }
  ]
}

API の使用方法

基本的な実装（JavaScript / TypeScript）

const BASE_URL =
  import.meta.env.VITE_3DSS_API_BASE_URL ||
  "https://us-central1-shapeshare3d.cloudfunctions.net/api";

// モデル一覧取得
async function fetchModels({ limit = 10 } = {}) {
  const res = await fetch(`${BASE_URL}/models/v1?limit=${limit}`);
  if (!res.ok) {
    throw new Error(`Failed: ${res.status} ${res.statusText}`);
  }
  return await res.json(); // { items: [...] }
}

// 単一モデル取得
async function fetchModelById(id) {
  const res = await fetch(`${BASE_URL}/models/v1/${encodeURIComponent(id)}`);
  if (!res.ok) {
    throw new Error(`Failed: ${res.status} ${res.statusText}`);
  }
  return await res.json(); // { id, title, ... }
}

React コンポーネントでの利用例

import { useState, useEffect } from 'react';
import { fetchModels } from './threeDssApi';

export default function ModelList() {
  const [items, setItems] = useState([]);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    fetchModels({ limit: 20 })
      .then(data => setItems(data.items))
      .catch(err => console.error(err))
      .finally(() => setLoading(false));
  }, []);

  return (
    <div>
      {loading ? '読み込み中...' : `${items.length}個のモデルを表示中`}
    </div>
  );
}

セキュリティと CORS 設定

S.Models API は現在、公開モデルを誰でも読めることを目的として設計されています。

• CORS 設定： Express 側で全許可（origin: true）
• Firestore ルール： 「public モデルだけ read を許可」
• アクセス範囲： 読み取り専用操作のみを提供

const functions = require("firebase-functions/v2/https");
const express = require("express");
const cors = require("cors");
const app = express();

app.use(cors({ origin: true }));
app.use(express.json());

// ここに /models/v1 などのルートを定義
exports.api = functions.onRequest(app);

将来のセキュリティ強化予定：

• CORS 制限： origin をホワイトリスト方式へ変更
• 認証機能： 読み取り以外の操作に Firebase Auth トークンまたは独自 API キーを要求
• 書き込み保護： お気に入り登録、ボード保存、削除などの操作を厳格に保護

新規アプリ開発時のベストプラクティス

1. クライアントモジュールの配置： 各アプリに threeDssApi.js / .ts を置き、SDK として統一した呼び出し方を実現する
2. 環境変数で BASE_URL を設定： Vite なら VITE_3DSS_API_BASE_URL、Next.js なら NEXT_PUBLIC_3DSS_API_BASE_URL などで切り替える
3. アプリ固有データと modelId の紐付け： アプリのエンティティに modelId を参照フィールドとして持たせる
4. 必要時に API 呼び出し： 一覧表示や詳細表示など、画面で必要なタイミングで取得する

今後の展望

S.Models API は今後、以下の機能拡張を計画しています。

• /models/v1/search — キーワード・タグ・カテゴリによる検索
• /models/v1/:id/files — GLB / 3DM 等のダウンロード URL やメタデータ提供
• /users/v1/:id — ユーザーの公開プロフィール取得
• /boards/v1/:id — 公開ボードのサマリ情報取得

将来的には Unity、Unreal Engine、Rhino といった外部ツールからのアクセスも想定しています。共通データは API 側に集約し、各アプリは ID を持つだけで詳細を動的取得する——この運用ポリシーで、整合性とスケーラビリティを最優先に設計を進めます。

まとめ

S.Models API は、複数アプリケーション間での3Dモデルデータ共有を効率化するプラットフォーム API です。プラットフォーム層とアプリ層を明確に分離することで、整合性を保ちながら開発効率を大幅に向上できます。現在は3Dモデルデータの取得機能が中心ですが、今後はユーザー管理・ボード管理・検索機能など、より包括的なプラットフォーム API へと発展させていきます。