{"openapi":"3.1.0","info":{"title":"Global Digital Identity Public API","version":"1.0.0","description":"去中心化身份与会员管理系统的公开 REST API。所有端点强制 TLS 1.3；敏感操作需携带 `Authorization: Bearer <token>` 与 `X-Node-Signature` 节点签名。","contact":{"name":"Global Digital Identity Foundation","url":"https://globaldigitalid.net"},"license":{"name":"Apache-2.0"}},"servers":[{"url":"https://globaldigitalid.net","description":"Production"}],"tags":[{"name":"Members","description":"身份与成员管理"},{"name":"Attestations","description":"链上存证事件流"},{"name":"Stats","description":"全网统计与节点遥测"},{"name":"ZK","description":"零知识属性核验"}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"节点签发的 Bearer Token。"},"NodeSignature":{"type":"apiKey","in":"header","name":"X-Node-Signature","description":"由节点私钥对请求体进行 Ed25519 签名后得到的十六进制字符串。"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string","example":"invalid_input"},"message":{"type":"string"}}}}},"paths":{"/api/public/members/register":{"post":{"tags":["Members"],"summary":"注册身份并签发 Global Digital Identity 与 VC","security":[{"BearerAuth":[],"NodeSignature":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["subjectCode","regionCode","holderName"],"properties":{"subjectCode":{"type":"string","enum":["1001","1002","1003","1004","1005","1006"],"description":"主体类型代码（1001 自然人 / 1002 法人 …）"},"regionCode":{"type":"string","example":"CN-01"},"holderName":{"type":"string","example":"Alice Chen"},"mnemonicLength":{"type":"integer","enum":[12,24],"default":12}}},"example":{"subjectCode":"1001","regionCode":"CN-01","holderName":"Alice Chen","mnemonicLength":12}}}},"responses":{"201":{"description":"身份创建成功，返回 Global Digital Identity、DID、助记词与 W3C VC。","content":{"application/json":{"example":{"ok":true,"gdiId":"732815940192837104","did":"did:gdi:732815940192837104","subjectType":"natural_person","regionCode":"CN-01","regionLabel":"中国 · 上海","txHash":"0x9f3c1ab4e7d2061b8af31729cd5b48e60a2c7d5f9183642aeb15c70efa92cd","blockHeight":18127345,"issuedAt":"2026-05-23T08:14:22.118Z","mnemonic":["abandon","ability","able","about","above","absent","absorb","abstract","absurd","abuse","access","accident"],"vc":{"@context":["https://www.w3.org/ns/credentials/v2","https://globaldigitalid.net/contexts/v1"],"type":["VerifiableCredential","GlobalDigitalIdentityCredential"],"issuer":"did:gdi:node:CN-01","validFrom":"2026-05-23T08:14:22.118Z","credentialSubject":{"id":"did:gdi:732815940192837104","gdiId":"732815940192837104","subjectType":"natural_person","regionCode":"CN-01","regionLabel":"中国 · 上海","holderName":"Alice Chen"},"proof":{"type":"DataIntegrityProof","cryptosuite":"eddsa-rdfc-2022","created":"2026-05-23T08:14:22.118Z","verificationMethod":"did:gdi:node:CN-01#key-1","proofPurpose":"assertionMethod","proofValue":"0x9f3c1ab4e7d2061b8af31729cd5b48e60a2c7d5f9183642aeb15c70efa92cd"}}}}}},"401":{"description":"缺失或无效的 Bearer / 节点签名"},"422":{"description":"请求体校验失败"},"500":{"description":"签发或存证失败"}}}},"/api/public/members/recent":{"get":{"tags":["Members"],"summary":"获取最近注册的公开成员列表","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"返回按时间倒序的成员列表","content":{"application/json":{"example":{"ok":true,"count":2,"members":[{"id":"732815940192837104","subject_code":"1001","subject_type":"natural_person","region_code":"CN-01","region_label":"中国 · 上海","holder_name":"Alice Chen","status":"active","created_at":"2026-05-23T08:14:22.118Z"},{"id":"732815940071904512","subject_code":"1002","subject_type":"legal_entity","region_code":"SEA-02","region_label":"新加坡","holder_name":"Orion Labs Pte Ltd","status":"active","created_at":"2026-05-23T07:58:11.402Z"}]}}}}}}},"/api/public/attestations":{"get":{"tags":["Attestations"],"summary":"列出链上存证事件流","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100}},{"name":"event_type","in":"query","schema":{"type":"string","enum":["register","verify","revoke","update"]}},{"name":"member_id","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"返回存证事件","content":{"application/json":{"example":{"ok":true,"count":1,"items":[{"id":481923,"member_id":"732815940192837104","event_type":"register","node_code":"CN-01","tx_hash":"0x9f3c1ab4e7d2061b8af31729cd5b48e60a2c7d5f9183642aeb15c70efa92cd","block_height":18127345,"payload":{"subject":"1001","holder":"Alice Chen","source":"api"},"created_at":"2026-05-23T08:14:22.118Z"}]}}}}}}},"/api/public/stats/global":{"get":{"tags":["Stats"],"summary":"实时节点状态、成员分布与流量指标","responses":{"200":{"description":"全局统计快照","content":{"application/json":{"example":{"ok":true,"generatedAt":"2026-05-23T08:20:00.000Z","totals":{"members":1284910,"attestations":9382014,"attestations24h":41203,"nodes":7},"byRegion":[{"code":"CN-01","label":"中国 · 上海","count":412305},{"code":"EU-03","label":"法兰克福","count":287012}],"byEventType":{"register":1284910,"verify":7918204,"revoke":1820},"nodes":[{"code":"CN-01","label":"中国 · 上海","status":"active","consensusLatencyMs":942,"tps":318,"uptimePct":99.87}]}}}}}}},"/api/public/zk/verify":{"post":{"tags":["ZK"],"summary":"零知识属性核验","security":[{"BearerAuth":[],"NodeSignature":[]}],"requestBody":{"required":true,"content":{"application/json":{"example":{"gdiId":"732815940192837104","claims":[{"attribute":"age_over","value":18},{"attribute":"region_in","value":["CN-01","SEA-02"]}],"proof":{"scheme":"groth16","publicSignals":["0x01","0x9f"],"proof":"0x2af3...c19d (groth16 proof bytes, base16-encoded, length 192-256 bytes)"},"nonce":"8f3a91c0b27e"}}}},"responses":{"200":{"description":"核验结果（成功或失败）","content":{"application/json":{"example":{"ok":true,"verified":true,"gdiId":"732815940192837104","scheme":"groth16","results":[{"attribute":"age_over","value":18,"satisfied":true},{"attribute":"region_in","value":["CN-01","SEA-02"],"satisfied":true}],"verificationId":"0x71fa92cd0e8b4c1d5a3f29ab6e7194c8d20b3f5a1e4c9d72ab8f061c3e92zk","verifiedAt":"2026-05-23T08:21:48.221Z","nonce":"8f3a91c0b27e"}}}},"401":{"description":"缺失或无效的鉴权头"},"404":{"description":"subject_not_found"},"409":{"description":"subject_inactive"},"422":{"description":"请求体校验失败"}}}}}}