Documentation, SDKs और API Governance

Developer अनुभव ही उत्पाद है

अच्छे docs में quick start होता है जो मिनटों में पहली सफल call कराए, OpenAPI spec से बना reference, आम कामों के guides, कई भाषाओं में चलने योग्य उदाहरण, ईमानदार changelog और error catalogue। परीक्षण डेटा और keys वाला sandbox दें। लोकप्रिय भाषाओं के लिए generated या हाथ से बने SDKs authentication, retries, pagination और idempotency छिपाते हैं; उन्हें API की तरह ही version और test करें। कई टीमों के साथ governance जोड़ें: लिखित API style guide (नामकरण, errors, pagination, versioning), specs की स्वचालित linting (जैसे Spectral नियमों से), नए endpoints शिप होने से पहले API review चरण, APIs और मालिकों की केंद्रीय सूची, और latency, error दर, adoption तथा पहली-call-तक-का-समय जैसे मापदंड। Governance को टीमों को एकरूप शिप करने योग्य बनाना चाहिए, उन्हें धीमा नहीं।

Style guide का अंश

छोटे, परखे जा सकने वाले नियम lint करना और पालन करना आसान हैं।

1. Paths: lowercase, plural nouns, hyphen-separated; max 2 levels of nesting.
2. JSON fields: snake_case; timestamps in ISO 8601 UTC; money as integer minor units + currency.
3. Collections: cursor pagination, default limit 20, max 100; next_cursor null at the end.
4. Errors: application/problem+json with type, title, status, detail, request_id.
5. POST with side effects requires Idempotency-Key.
6. Breaking changes need a new major version, a migration guide and 6 months' notice.
7. Every operation has operationId, summary, error responses and an example.

त्वरित जाँच: API governance का उद्देश्य क्या है?

• दस्तावेज़ हटाना
• सभी releases धीमे करना
• डिलीवरी रोके बिना टीमों में एकरूप, उच्च-गुणवत्ता वाले APIs
• versioning से हमेशा बचना