trustgraph/docs/tech-specs/openapi-spec.hi.md

---
layout: default
title: "OpenAPI विनिर्देश - तकनीकी विनिर्देश"
parent: "Hindi (Beta)"
---

# OpenAPI विनिर्देश - तकनीकी विनिर्देश

> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.

## लक्ष्य

ट्रस्टग्राफ REST API गेटवे के लिए एक व्यापक, मॉड्यूलर OpenAPI 3.1 विनिर्देश बनाना जो:
सभी REST एंडपॉइंट्स का दस्तावेजीकरण करता है
मॉड्यूलरिटी और रखरखाव के लिए बाहरी `$ref` का उपयोग करता है
सीधे संदेश अनुवाद कोड से मेल खाता है
सटीक अनुरोध/प्रतिक्रिया स्कीमा प्रदान करता है

## सत्य का स्रोत

API को निम्नलिखित द्वारा परिभाषित किया गया है:
**संदेश अनुवादक**: `trustgraph-base/trustgraph/messaging/translators/*.py`
**डिस्पैचर मैनेजर**: `trustgraph-flow/trustgraph/gateway/dispatch/manager.py`
**एंडपॉइंट मैनेजर**: `trustgraph-flow/trustgraph/gateway/endpoint/manager.py`

## निर्देशिका संरचना

```
openapi/
├── openapi.yaml                          # Main entry point
├── paths/
│   ├── config.yaml                       # Global services
│   ├── flow.yaml
│   ├── librarian.yaml
│   ├── knowledge.yaml
│   ├── collection-management.yaml
│   ├── flow-services/                    # Flow-hosted services
│   │   ├── agent.yaml
│   │   ├── document-rag.yaml
│   │   ├── graph-rag.yaml
│   │   ├── text-completion.yaml
│   │   ├── prompt.yaml
│   │   ├── embeddings.yaml
│   │   ├── mcp-tool.yaml
│   │   ├── triples.yaml
│   │   ├── objects.yaml
│   │   ├── nlp-query.yaml
│   │   ├── structured-query.yaml
│   │   ├── structured-diag.yaml
│   │   ├── graph-embeddings.yaml
│   │   ├── document-embeddings.yaml
│   │   ├── text-load.yaml
│   │   └── document-load.yaml
│   ├── import-export/
│   │   ├── core-import.yaml
│   │   ├── core-export.yaml
│   │   └── flow-import-export.yaml      # WebSocket import/export
│   ├── websocket.yaml
│   └── metrics.yaml
├── components/
│   ├── schemas/
│   │   ├── config/
│   │   ├── flow/
│   │   ├── librarian/
│   │   ├── knowledge/
│   │   ├── collection/
│   │   ├── ai-services/
│   │   ├── common/
│   │   └── errors/
│   ├── parameters/
│   ├── responses/
│   └── examples/
└── security/
    └── bearerAuth.yaml
```

## सर्विस मैपिंग

### ग्लोबल सर्विसेज (`/api/v1/{kind}`)
`config` - कॉन्फ़िगरेशन प्रबंधन
`flow` - फ्लो लाइफसाइकिल
`librarian` - दस्तावेज़ लाइब्रेरी
`knowledge` - नॉलेज कोर
`collection-management` - कलेक्शन मेटाडेटा

### फ्लो-होस्टेड सर्विसेज (`/api/v1/flow/{flow}/service/{kind}`)

**अनुरोध/प्रतिक्रिया:**
`agent`, `text-completion`, `prompt`, `mcp-tool`
`graph-rag`, `document-rag`
`embeddings`, `graph-embeddings`, `document-embeddings`
`triples`, `objects`, `nlp-query`, `structured-query`, `structured-diag`

**फायर-एंड-फॉरगेट:**
`text-load`, `document-load`

### इम्पोर्ट/एक्सपोर्ट
`/api/v1/import-core` (POST)
`/api/v1/export-core` (GET)
`/api/v1/flow/{flow}/import/{kind}` (WebSocket)
`/api/v1/flow/{flow}/export/{kind}` (WebSocket)

### अन्य
`/api/v1/socket` (WebSocket मल्टीप्लेक्स)
`/api/metrics` (Prometheus)

## दृष्टिकोण

### चरण 1: सेटअप
1. डायरेक्टरी संरचना बनाएं
2. मुख्य `openapi.yaml` बनाएं जिसमें मेटाडेटा, सर्वर, सुरक्षा शामिल हो
3. पुन: प्रयोज्य घटक बनाएं (त्रुटियां, सामान्य पैरामीटर, सुरक्षा योजनाएं)

### चरण 2: सामान्य स्कीमा
साझा स्कीमा बनाएं जिनका उपयोग सेवाओं में किया जाता है:
`RdfValue`, `Triple` - RDF/ट्रिपल संरचनाएं
`ErrorObject` - त्रुटि प्रतिक्रिया
`DocumentMetadata`, `ProcessingMetadata` - मेटाडेटा संरचनाएं
सामान्य पैरामीटर: `FlowId`, `User`, `Collection`

### चरण 3: ग्लोबल सर्विसेज
प्रत्येक ग्लोबल सर्विस (कॉन्फ़िग, फ्लो, लाइब्रेरियन, नॉलेज, कलेक्शन-मैनेजमेंट) के लिए:
1. `paths/` में पाथ फ़ाइल बनाएं
2. `components/schemas/{service}/` में अनुरोध स्कीमा बनाएं
3. प्रतिक्रिया स्कीमा बनाएं
4. उदाहरण जोड़ें
5. मुख्य `openapi.yaml` से संदर्भ लें

### चरण 4: फ्लो-होस्टेड सर्विसेज
प्रत्येक फ्लो-होस्टेड सर्विस के लिए:
1. `paths/flow-services/` में पाथ फ़ाइल बनाएं
2. `components/schemas/ai-services/` में अनुरोध/प्रतिक्रिया स्कीमा बनाएं
3. जहां लागू हो, स्ट्रीमिंग फ़्लैग दस्तावेज़ जोड़ें
4. मुख्य `openapi.yaml` से संदर्भ लें

### चरण 5: इम्पोर्ट/एक्सपोर्ट और WebSocket
1. मुख्य इम्पोर्ट/एक्सपोर्ट एंडपॉइंट्स का दस्तावेज़ बनाएं
2. WebSocket प्रोटोकॉल पैटर्न का दस्तावेज़ बनाएं
3. फ्लो-लेवल इम्पोर्ट/एक्सपोर्ट WebSocket एंडपॉइंट्स का दस्तावेज़ बनाएं

### चरण 6: सत्यापन
1. OpenAPI सत्यापन उपकरणों के साथ सत्यापित करें
2. Swagger UI के साथ परीक्षण करें
3. सत्यापित करें कि सभी अनुवादक कवर किए गए हैं

## फ़ील्ड नामकरण सम्मेलन

सभी JSON फ़ील्ड **केबाब-केस** का उपयोग करते हैं:
`flow-id`, `blueprint-name`, `doc-limit`, `entity-limit`, आदि।

## स्कीमा फ़ाइलें बनाना

प्रत्येक अनुवादक के लिए `trustgraph-base/trustgraph/messaging/translators/`:

1. **अनुवादक `to_pulsar()` विधि पढ़ें** - अनुरोध स्कीमा को परिभाषित करता है
2. **अनुवादक `from_pulsar()` विधि पढ़ें** - प्रतिक्रिया स्कीमा को परिभाषित करता है
3. **फ़ील्ड नाम और प्रकार निकालें**
4. **OpenAPI स्कीमा बनाएं** जिसमें:
   फ़ील्ड नाम (केबाब-केस)
   प्रकार (स्ट्रिंग, पूर्णांक, बूलियन, ऑब्जेक्ट, सरणी)
   आवश्यक फ़ील्ड
   डिफ़ॉल्ट
   विवरण

### उदाहरण मैपिंग प्रक्रिया

```python
# From retrieval.py DocumentRagRequestTranslator
def to_pulsar(self, data: Dict[str, Any]) -> DocumentRagQuery:
    return DocumentRagQuery(
        query=data["query"],                              # required string
        user=data.get("user", "trustgraph"),             # optional string, default "trustgraph"
        collection=data.get("collection", "default"),     # optional string, default "default"
        doc_limit=int(data.get("doc-limit", 20)),        # optional integer, default 20
        streaming=data.get("streaming", False)            # optional boolean, default false
    )
```

अनुवाद:

```yaml
# components/schemas/ai-services/DocumentRagRequest.yaml
type: object
required:
  - query
properties:
  query:
    type: string
    description: Search query
  user:
    type: string
    default: trustgraph
  collection:
    type: string
    default: default
  doc-limit:
    type: integer
    default: 20
    description: Maximum number of documents to retrieve
  streaming:
    type: boolean
    default: false
    description: Enable streaming responses
```

## स्ट्रीमिंग प्रतिक्रियाएं

वे सेवाएं जो स्ट्रीमिंग का समर्थन करती हैं, वे `end_of_stream` ध्वज के साथ कई प्रतिक्रियाएं लौटाती हैं:
`agent`, `text-completion`, `prompt`
`document-rag`, `graph-rag`

इस पैटर्न को प्रत्येक सेवा की प्रतिक्रिया स्कीमा में प्रलेखित करें।

## त्रुटि प्रतिक्रियाएं

सभी सेवाएं निम्नलिखित लौटा सकती हैं:
```yaml
error:
  oneOf:
    - type: string
    - $ref: '#/components/schemas/ErrorObject'
```

जहाँ `ErrorObject` है:
```yaml
type: object
properties:
  type:
    type: string
  message:
    type: string
```

## संदर्भ

अनुवादक: `trustgraph-base/trustgraph/messaging/translators/`
डिस्पैचर मैपिंग: `trustgraph-flow/trustgraph/gateway/dispatch/manager.py`
एंडपॉइंट रूटिंग: `trustgraph-flow/trustgraph/gateway/endpoint/manager.py`
सेवा सारांश: `API_SERVICES_SUMMARY.md`