未分類

3DSS-API解説 - 3Dモデルデータを共有するプラットフォームAPIの全貌3DSS-API 技術ドキュメント

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

3dss_api_technical_documentation_20251124221242ダウンロード

3DSS-APIとは何か？なぜ必要なのか

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

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

3DSS-APIの主なメリット：

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

3DSS-APIの概要

プロジェクト構成

3DSS-APIは以下の技術スタックで構築されています：

  • プロジェクト名： 036-3dss-api（ローカルのAPI専用プロジェクト）
  • Firebaseプロジェクト： shapeshare3d（本番の3D Shape Shareと同一）
  • 実行環境： Cloud Functions + Express
  • データベース： Firestore

Base URL

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

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

  • GET /models/v1 - モデル一覧取得
  • GET /models/v1/:id - 単一モデル取得

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

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

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

アーキテクチャの概念

【アプリ層】
インテリアかるた、Webプレゼン、シミュレーション等の各アプリケーション
→ それぞれ独自のFirestore/DBを持ってもOK

【プラットフォーム層】
3DSS-API（共通データへのアクセス窓口）
→ 3Dモデル、ユーザー、チーム、ボード、共通タグなどを管理

データ共有の原則

各アプリケーションは以下の原則に従ってデータを扱います：

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

このアプローチのメリット：

  • どのアプリからでも同じBase URLで共通3Dデータにアクセス可能
  • データの整合性が保たれる
  • アプリ間でのデータ連携が容易
  • データ更新時の影響範囲を最小限に抑制

現在のAPI仕様

現在提供されている3DSS-APIのエンドポイントは以下の通りです：

メソッドエンドポイント説明パラメータレスポンス
GET/models/v1モデル一覧取得
（学習/デモ用）		limit（任意、デフォルト10）200 OK
GET/models/v1/:id単一モデルの詳細情報取得id（必須）200 OK / 404 Not Found

レスポンス形式

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

フィールド説明型
idモデルの一意識別子string
slugURL用識別子string
titleモデル名string
thumbnailUrlサムネイルURLstring
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）

標準のfetch APIを使用した基本的な実装例です：

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/Viteでの実装例

Reactアプリケーションで使用する共通クライアントモジュールの例：

// src/threeDssApi.js
export const THREE_DSS_API_BASE_URL =
  import.meta.env.VITE_3DSS_API_BASE_URL || 
  "https://us-central1-shapeshare3d.cloudfunctions.net/api";

export async function fetchModelById(modelId) {
  if (!modelId) throw new Error("modelId is required");
  
  const url = `${THREE_DSS_API_BASE_URL}/models/v1/${encodeURIComponent(modelId)}`;
  const res = await fetch(url);
  
  if (!res.ok) {
    const text = await res.text().catch(() => "");
    throw new Error(
      `Failed to fetch model ${modelId}: ${res.status} ${res.statusText} ${text}`
    );
  }
  
  return res.json();
}

export async function fetchModels({ limit = 10 } = {}) {
  const url = `${THREE_DSS_API_BASE_URL}/models/v1?limit=${limit}`;
  const res = await fetch(url);
  
  if (!res.ok) {
    throw new Error(`Failed: ${res.status} ${res.statusText}`);
  }
  
  return res.json();
}

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

import { useState, useEffect } from 'react';
import { fetchModels, fetchModelById } 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設定

現在のセキュリティアプローチ

3DSS-APIは現在、公開モデルを誰でも読めることを目的として設計されています：

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

Express設定例

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

// CORS を全世界許可（学習・デモ用）
app.use(cors({ origin: true }));
app.use(express.json());

// ここに /models/v1 などのルートを定義
// ...

exports.api = functions.onRequest(app);

将来のセキュリティ強化計画

予定されているセキュリティ強化：

  • CORS制限： originをホワイトリスト方式に変更
    例：["https://3dshapeshare.com", "https://your-other-app.com"]
  • 認証機能： 読み取り以外の操作にFirebase Authトークンまたは独自APIキーを要求
  • 書き込み保護： お気に入り登録、ボード保存、削除などの操作を厳格に保護

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

3DSS-APIを使用した新規アプリケーション開発では、以下の4ステップを推奨します：

1クライアントモジュールの配置

各アプリにAPI呼び出し用のモジュールを配置します：

  • threeDssApi.js（JavaScript版）
  • threeDssApi.ts（TypeScript版）

このモジュールがSDKの役割を果たし、全アプリで統一した呼び出し方を実現します。

2環境変数でBASE_URLを設定

フレームワーク別の環境変数設定例：

# Vite / React (.env.local)
VITE_3DSS_API_BASE_URL="https://us-central1-shapeshare3d.cloudfunctions.net/api"

# Next.js (.env.local)  
NEXT_PUBLIC_3DSS_API_BASE_URL="https://us-central1-shapeshare3d.cloudfunctions.net/api"

# Node バックエンド (.env)
THREE_DSS_API_BASE_URL=https://us-central1-shapeshare3d.cloudfunctions.net/api

3アプリ固有データとmodelIdの紐付け

アプリのエンティティに3DSSモデルIDを参照フィールドとして持たせます：

{
  id: "ne-nekko",
  syllable: "ね", 
  keyword: "根っこのコンセプト",
  modelId: "0052b495-4cf6-42be-b597-ea83340a86c9", // ← 3DSSモデルとの紐づけ
  // その他アプリ固有のフィールド
}

4必要時にAPI呼び出し

画面で必要なタイミングでAPIを呼び出します：

import { fetchModelById, fetchModels } from "./threeDssApi";

// 一覧表示画面などで
useEffect(() => {
  fetchModels({ limit: 20 }).then((data) => setItems(data.items));
}, []);

// 詳細画面では  
useEffect(() => {
  if (modelId) {
    fetchModelById(modelId).then((model) => setModelData(model));
  }
}, [modelId]);

これにより、どのアプリからも統一的なインターフェースで3Dモデルデータにアクセスできます。

今後の展望

3DSS-APIは今後、以下の機能拡張が計画されています：

エンドポイント拡張計画

エンドポイント機能説明
/models/v1/searchモデル検索キーワード、タグ、カテゴリによる検索機能
/models/v1/:id/filesファイル管理GLB、3DM等のダウンロードURLやメタデータ提供
/users/v1/:idユーザー情報ユーザーの公開プロフィール取得
/boards/v1/:idボード管理公開ボードのサマリ情報取得

外部ツール連携

将来的には以下のツールからのアクセスも想定されています：

  • Unity - ゲーム開発エンジンからのプラグイン経由アクセス
  • Unreal Engine - リアルタイム3Dエンジンでの利用
  • Rhino - 3DCADソフトウェアでのデザイン連携

運用ポリシー

基本運用ルール：

  • 共通データは全て「3DSS-API側」に集約
  • 各アプリは「modelId / userId / boardId を持つだけ」でデータの詳細はAPIから動的取得
  • データの整合性とスケーラビリティを最優先に設計

まとめ

3DSS-APIは、複数のアプリケーション間での3Dモデルデータ共有を効率化するための強力なプラットフォームAPIです。プラットフォーム層とアプリ層の明確な分離により、データの整合性を保ちながら開発効率を大幅に向上させることができます。

3DSS-APIの主な特徴：

  • 統一されたアクセス方法： 単一のBase URLから全ての共通データにアクセス
  • 疎結合設計： 各アプリは独立性を保ちながらデータを共有
  • スケーラブルな拡張性： 将来的な機能追加を見据えた設計
  • 開発者フレンドリー： シンプルなREST APIインターフェース

現在は3Dモデルデータの取得機能のみですが、今後はユーザー管理、ボード管理、検索機能など、より包括的なプラットフォームAPIへと発展していく予定です。

3Dアプリケーション開発に携わる開発者の方は、ぜひ3DSS-APIの活用を検討してみてください。効率的なデータ共有基盤として、開発プロセスの大幅な改善が期待できます。

-未分類