ひとつのAPI

01

はじめに

スキーマの各コレクションは、おなじみの5操作（一覧、読み取り、作成、更新、削除）と件数取得を備えたRESTリソースです。APIはPayload CMSがTypeScriptのスキーマから生成するため、モデルとも権限ともずれません。管理画面が許すことが、そのままAPIが許すことです。

規約：UTF-8のJSON、数値id、ISO 8601の日付（UTC）、slugとselectの値はアクセントなしのスペイン語（テキストではなく識別子）、書き込み時は Content-Type: application/json。GraphQLは無効で、すべてRESTです。

• ベースURL：https://dwfw.trabemflex.com/api（開発環境では http://localhost:3000/api）。
• バージョン：APIはリポジトリのスキーマのバージョンに従う。破壊的変更はREADMEと本書で告知。
• 人気指標なし：どのリソースにも、いいね・閲覧数・ランキングはない（原則：アルゴリズム的エポケー）。

02

クイックスタート

3回の呼び出しで仕組みがわかる：ログインなしで公開データ、ログイン、ログイン後の読み取り。

# 1 · ログインなし：公開データ（アーカイブ）、英語で
curl "https://dwfw.trabemflex.com/api/obras?locale=en&depth=1&limit=20"

# 2 · ログイン（payload-token クッキーを設定しJWTを返す）
TOKEN=$(curl -s -H "Content-Type: application/json" \
  -d '{"email":"media@dwfw.test","password":"dwfw-demo-2026"}' \
  "https://dwfw.trabemflex.com/api/usuarios/login" | jq -r .token)

# 3 · ログイン後：権限が許す範囲すべて
curl -H "Authorization: JWT $TOKEN" "https://dwfw.trabemflex.com/api/obras?locale=en&depth=1"

03

認証

セッションはPayloadのものです。POST /api/usuarios/login に email と password を送ると、ユーザー、JWT、その期限（exp）を返し、HttpOnlyの payload-token クッキーを設定します。どちらの経路でも使えます：クッキー（ブラウザ、credentials: include。CSRF保護により自サイトのオリジンからのみ受け付け）または Authorization: JWT <token> ヘッダー（サーバー、スクリプト、アプリ：ブラウザ外では必須）。トークンは2時間で期限切れ。/api/usuarios/refresh-token でパスワードを再入力せずに更新できます。

GET /api/usuarios/me はセッションのユーザーを返します（なければ user: null）。GET /api/access は現在のセッションで各コレクションのどの操作・どのフィールドが許されるかを要約します。ロールに応じたUIを作るための推奨手段です。

# ログイン：ユーザーとJWTを返し、payload-token クッキー（HttpOnly）を設定
curl -H "Content-Type: application/json" \
  -d '{"email":"media@dwfw.test","password":"dwfw-demo-2026"}' \
  "https://dwfw.trabemflex.com/api/usuarios/login"
# → { "user": { … }, "token": "<jwt>", "exp": 1790000000 }   (+ cookie payload-token)

# Authorization: JWT ヘッダーで（スクリプト、サーバー、アプリ）
curl -H "Authorization: JWT <token>" "https://dwfw.trabemflex.com/api/usuarios/me"

# ブラウザではクッキーで十分（同一オリジン。csrf有効時は、正しいOriginヘッダーがないとクッキーは無視される）
fetch('/api/usuarios/me', { credentials: 'include' })

# 期限切れ前にトークンを更新（既定2時間）
curl -H "Authorization: JWT <token>" -X POST "https://dwfw.trabemflex.com/api/usuarios/refresh-token"

# このセッションが各コレクション・各フィールドでできること
curl -H "Authorization: JWT <token>" "https://dwfw.trabemflex.com/api/access"

# ログアウト
curl -H "Authorization: JWT <token>" -X POST "https://dwfw.trabemflex.com/api/usuarios/logout"

04

権限：ロールと権限項目

アクセスはビューではなく権限ベースのRBACが決めます。ユーザーは複数のロールを持ち、各ロールは権限の集合へのショートカット。付与は個別の権限を期限付き（任意）で追加し、自動で失効します。下の表はコード（src/access/capabilities.ts）から生成しています。

さらに二つの制限：scopeEdiciones はパートナーの読み取りをそのエディションに限定し、obra:editar_propia は作者が自分の作者レコードに紐づく作品だけを触れるようにします。権限のないリクエストは403。制限された読み取りは許可分だけを返します（Mediaは obra:leer がなくアーカイブのみ）。

05

クエリ：パラメータ、フィルター、ページネーション

すべての一覧は同じパラメータを受け付けます。一覧レスポンスはメタデータ付きでページ分割されます（totalDocs、totalPages、nextPage…）。

演算子

# ページ付き・ソート済み一覧、日本語コンテンツ、リレーションを2階層解決
curl "https://dwfw.trabemflex.com/api/obras?locale=ja&depth=2&limit=10&page=1&sort=-updatedAt"

# 単純なフィルター：アーカイブの作品（工程7）
curl -g "https://dwfw.trabemflex.com/api/obras?where[estadoCuratorial][equals]=movimiento_7"

# 複合フィルター：and / in / exists
curl -g "https://dwfw.trabemflex.com/api/obras?where[and][0][tipo][in]=modelo_3d,avatar&where[and][1][edicion][exists]=true"

# ポリモーフィックなリレーション：value と relationTo の両方で絞る（idはコレクション間で重複する）
curl -g "https://dwfw.trabemflex.com/api/conexiones?where[or][0][origen.value][equals]=1&where[or][0][origen.relationTo][equals]=obras"

# 一部のフィールドのみ（軽いレスポンス）
curl -g "https://dwfw.trabemflex.com/api/obras?select[titulo]=true&select[estadoCuratorial]=true&depth=0"

# ドキュメントを取得せずに件数のみ
curl -g "https://dwfw.trabemflex.com/api/obras/count?where[estadoCuratorial][equals]=movimiento_7"

{
  "docs": [ { "id": 3, "titulo": "Metsä · Micelio v3", "estadoCuratorial": "movimiento_7", "…": "…" } ],
  "totalDocs": 1,
  "limit": 10,
  "totalPages": 1,
  "page": 1,
  "pagingCounter": 1,
  "hasPrevPage": false,
  "hasNextPage": false,
  "prevPage": null,
  "nextPage": null
}

06

言語

コンテンツ（タイトル、説明、メモ、alt…）は言語ごとに保存：スペイン語（既定）、英語、簡体字中国語、日本語。?locale= で要求し、翻訳がなければスペイン語が返るため空にはなりません。?locale=all はすべての翻訳を一度に返します（{ es, en, zh, ja }）。技術的なidは翻訳しません。データだからです。

別の言語で書くには ?locale=xx 付きのPATCHでローカライズ対象フィールドだけを送ります。リレーションや状態は言語で変わりません。各リソースのリファレンスの「ローカライズ」列がどのフィールドが対象かを示します。

07

書き込み

POSTは作成、PATCHは部分更新（送ったものだけ）、DELETEは削除。リレーションはidで送り、ポリモーフィックなものは { relationTo, value }。ファイルは multipart/form-data でMediaへ。

• バリデーション：必須項目とselectの値はサーバーで検査。400は項目と理由を返す。
• 原則のフック：Significadosでは procedencia=humano を強制。estadoCuratorial は movimiento:avanzar でのみ変更。作者は他人の作品を自分のものにできない。
• 冪等性：PATCHとDELETEは冪等。POSTは違う（呼ぶたびにドキュメントを作る）。

# 作成（obra:crear が必要）。指定したlocaleに保存。リレーションはid
curl -H "Authorization: JWT $TOKEN" -H "Content-Type: application/json" -X POST \
  -d '{"titulo":"Nueva obra","tipo":"modelo_3d","autor":1,"nodoOrigen":"laboratorio_ia"}' \
  "https://dwfw.trabemflex.com/api/obras?locale=es"
# → 201 { "message": "…", "doc": { "id": 4, … } }

# 別のlocaleでの部分更新：ローカライズ対象フィールドのみ。他は変わらない
curl -H "Authorization: JWT $TOKEN" -H "Content-Type: application/json" -X PATCH \
  -d '{"titulo":"New work","descripcionFormal":{"silueta":"…"}}' \
  "https://dwfw.trabemflex.com/api/obras/4?locale=en"

# 書き込み時のポリモーフィックなリレーション：{ relationTo, value }
curl -H "Authorization: JWT $TOKEN" -H "Content-Type: application/json" -X POST \
  -d '{"origen":{"relationTo":"obras","value":4},"destino":{"relationTo":"nodos","value":2},"tipoRelacion":"dialoga_con","procedencia":"humano","estado":"propuesta"}' \
  "https://dwfw.trabemflex.com/api/conexiones"

# 接続を確認（conexion:confirmar が必要。なければ明示的なメッセージ付きの403）
curl -H "Authorization: JWT $TOKEN" -X PATCH -H "Content-Type: application/json" \
  -d '{"estado":"confirmada","procedencia":"humano"}' "https://dwfw.trabemflex.com/api/conexiones/1"

# Mediaにファイルをアップロード：multipart で `file` と `_payload`（他フィールドのJSON）
curl -H "Authorization: JWT $TOKEN" -F "file=@look-03.png" -F '_payload={"alt":"Look 03"}' "https://dwfw.trabemflex.com/api/media"

# 削除（obra:borrar が必要）
curl -H "Authorization: JWT $TOKEN" -X DELETE "https://dwfw.trabemflex.com/api/obras/4"

08

リソースリファレンス

コレクションごとに1ブロック：パス、誰が読み誰が書くか、型とローカライズ付きのフィールド、そしてこのページ描画時に公開APIから取得した実例。

GET https://dwfw.trabemflex.com/api/obras?depth=0&locale=ja&limit=1

{
  "id": 3,
  "titulo": "Metsä · 菌糸体 v3",
  "tipo": "codigo_generativo",
  "autor": 3,
  "nodoOrigen": "laboratorio_ia",
  "estadoCuratorial": "movimiento_7",
  "descripcionFormal": {
    "silueta": null,
    "material": "シミュレートされた菌糸の成長をパターン生成器として。",
    "sintaxisVisual": "形は描かれるのではなく、育てられる。"
  },
  "activosTecnicos": {
    "docs": [],
    "hasNextPage": false
  },
  "edicion": null,
  "updatedAt": "2026-08-22T18:29:49.582Z",
  "createdAt": "2026-08-21T07:12:39.411Z"
}

GET https://dwfw.trabemflex.com/api/autores?depth=0&locale=ja&limit=1

{
  "id": 3,
  "nombre": "Lab Metsä",
  "tipo": "laboratorio",
  "origenCultural": "フィンランド・ヘルシンキ",
  "bio": "ジェネラティブ素材のラボ。",
  "trayectoria": "シミュレーションによるバイオテキスタイルに特化した学術スピンオフ。",
  "nodos": [],
  "taller": {
    "capacidad": null,
    "materiales": [],
    "tecnologias": [],
    "usaFibrasRecicladas": null,
    "fibrasRecicladasDetalle": null,
    "notasSostenibilidad": null,
    "procedencia": "humano"
  },
  "updatedAt": "2026-08-22T18:29:48.843Z",
  "createdAt": "2026-08-21T07:12:36.066Z"
}

GET https://dwfw.trabemflex.com/api/nodos?depth=0&locale=ja&limit=1

{
  "id": 4,
  "nombre": "生成モデル時代の作者性",
  "tipo": "tension_cultural",
  "descripcion": null,
  "updatedAt": "2026-08-22T18:29:49.224Z",
  "createdAt": "2026-08-21T07:12:36.120Z"
}

GET https://dwfw.trabemflex.com/api/conexiones?depth=0&locale=ja&limit=1

{
  "id": 6,
  "origen": {
    "relationTo": "obras",
    "value": 2
  },
  "destino": {
    "relationTo": "obras",
    "value": 1
  },
  "tipoRelacion": "conversacion_paralela_con",
  "procedencia": "maquina",
  "estado": "propuesta",
  "confirmadaPor": null,
  "confirmadaEn": null,
  "nota": "Coincidencia en el campo silueta: ambas describen la silueta por lo que le falta de sostén estructural. Aguacero 01: \"Volumen inflado, sin punto de apoyo.\" Kata: \"Hombro desestructurado: la autoridad se retira del cuerpo.\" Vocabulario compartido: \"sin punto de apoyo\" / \"desestructurado\" / \"se retira\" — en las dos la forma se define por la ausencia de estructura que la sostenga, no por lo que añade. Divergen en tipo (coleccion_digital vs modelo_3d), nodo de origen (comunidad_digital_emergente vs academico_investigador) y material (plástico de baja poligonización vs lana simulada), y no tienen conexión entre sí en la cartografía. Solo se usa la descripción formal; no se usa el significado asignado a Kata ni el origen cultural de los autores. Evidencia sintáctica, pendiente de lectura curatorial.",
  "updatedAt": "2026-09-03T07:10:25.005Z",
  "createdAt": "2026-09-03T07:10:25.005Z"
}

GET https://dwfw.trabemflex.com/api/significados?depth=0&locale=ja&limit=1

{
  "id": 2,
  "obra": 3,
  "tensionSubyacente": "jhksjhdkae",
  "lectura": [],
  "curador": 1,
  "procedencia": "humano",
  "updatedAt": "2026-09-04T12:02:19.341Z",
  "createdAt": "2026-09-04T12:02:19.340Z"
}

GET https://dwfw.trabemflex.com/api/movimientos?depth=0&locale=ja&limit=1

{
  "id": 21,
  "obra": 3,
  "movimiento": "movimiento_7",
  "estado": "en_curso",
  "responsable": 2,
  "procedencia": "humano",
  "updatedAt": "2026-08-21T07:12:40.179Z",
  "createdAt": "2026-08-21T07:12:40.179Z"
}

GET https://dwfw.trabemflex.com/api/ediciones?depth=0&locale=ja&limit=1

{
  "id": 1,
  "nombre": "DWFW · 第1回",
  "fechaInicio": "2027-03-12T00:00:00.000Z",
  "fechaFin": "2027-03-15T00:00:00.000Z",
  "ciudadAnfitriona": "マドリード",
  "paisEnFoco": "スペイン",
  "updatedAt": "2026-08-22T18:29:48.495Z",
  "createdAt": "2026-08-21T07:12:35.921Z",
  "fase": "antes",
  "cuentaAtras": 14562620
}

GET https://dwfw.trabemflex.com/api/capitulos?depth=0&locale=ja&limit=1

{
  "id": 3,
  "titulo": "対話 · 作者性と機械",
  "edicion": 1,
  "autor": 2,
  "duracionMin": 60,
  "seccion": "conversaciones",
  "continente": "america",
  "obras": [
    2
  ],
  "updatedAt": "2026-08-22T19:21:09.427Z",
  "createdAt": "2026-08-22T19:21:09.303Z"
}

GET https://dwfw.trabemflex.com/api/piezas?depth=0&locale=ja&limit=1

{
  "id": 3,
  "titulo": "Colectivo Aguacero との対話",
  "tipo": "conversacion",
  "capitulo": 3,
  "obra": 2,
  "urlStreaming": null,
  "updatedAt": "2026-08-22T19:21:09.874Z",
  "createdAt": "2026-08-22T19:21:09.764Z"
}

09

エラー

エラーは対応するHTTPコードと errors 配列を持つJSONで返ります。自前のフックは明示的なコード付きのAPIErrorを使い、メッセージはリクエストの言語（Accept-Language）です。

HTTP/1.1 403 Forbidden
{ "errors": [ { "message": "Confirmar una conexión es un acto semántico: requiere la capacidad conexion:confirmar." } ] }

HTTP/1.1 400 Bad Request
{ "errors": [ { "name": "ValidationError", "message": "The following field is invalid: titulo",
                "data": { "errors": [ { "message": "This field is required.", "path": "titulo" } ] } } ] }

10

OpenAPI、型、統合

OpenAPI 3.0仕様は同じconfigから生成されます。Postman、Insomnia、Stoplightに取り込むか、openapi-generatorでクライアントを生成してください。スキーマのTypeScript型は src/payload-types.ts にあります（pnpm generate:types で再生成）。

openapi.json をダウンロードpayload-types.ts · GitHub

// 最小のJavaScriptクライアント（ブラウザまたはNode 18+）
const API = 'https://dwfw.trabemflex.com/api'

const res = await fetch(`${API}/usuarios/login`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ email, password }),
  credentials: 'include', // ブラウザではクッキーで十分。サーバーではヘッダーを使う
})
const { token } = await res.json()

// ヘッダーのJWTで読み取り
const obras = await fetch(`${API}/obras?locale=ja&depth=1&limit=20`, {
  headers: { Authorization: `JWT ${token}` },
}).then((r) => r.json())

// スキーマのTypeScript型（src/payload-types.ts）
import type { Obra, Autor } from './payload-types'

11

ベストプラクティス

• 必要なものだけ要求する：depth=0 か 1、select[...] でレスポンスは大幅に軽くなる。
• 公開一覧は必ずページ分割（limit ≤ 100）し、安定した項目でソートする。
• ポリモーフィックなリレーションは value と relationTo の両方で絞る。
• ロール対応のUIでは、ロールをハードコードせずセッションごとに /api/access を一度問い合わせる。
• selectの値と権限は安定した識別子として扱う。クライアント側でラベルで翻訳し、値は決して改名しない。
• サーバーでは Authorization: JWT ヘッダーを使い refresh-token で更新。ブラウザではクッキーに任せる。