एपीआई डिज़ाइन की खास जानकारी

आपको Apigee Edge दस्तावेज़ दिख रहा है.
Apigee X के दस्तावेज़ पर जाएं. जानकारी

डिज़ाइन वाले चरण में, एपीआई के लिए ज़रूरी शर्तें तय की जाती हैं. एपीआई डिज़ाइनर के तौर पर, आपके पास उन सेवाओं की योजना बनाने का विकल्प होता है जिन्हें आपको उपभोक्ताओं को दिखाना है. साथ ही, उन सेवाओं को ऐक्सेस करने के लिए एपीआई डिज़ाइन किए जा सकते हैं. एपीआई से जुड़ी ज़रूरी शर्तों को पूरा करने के लिए, इनमें से कोई एक दस्तावेज़ बनाएं:

  • OpenAPI दस्तावेज़
  • GraphQL स्कीमा

नीचे दिए गए सेक्शन में, OpenAPI और GraphQL दस्तावेज़ों के बारे में ज़्यादा जानकारी दी गई है. साथ ही, यह भी बताया गया है कि आपके एपीआई के लाइफ़साइकल में उनकी क्या भूमिका है. एपीआई के डिज़ाइन के दो विकल्पों की तुलना करने के लिए, इस ब्लॉग पोस्ट में REST और GraphQL की तुलना देखें.

OpenAPI की खास बातें क्या हैं?


"OpenAPI Initiative (OAI) का मकसद, स्वैगर के स्पेसिफ़िकेशन के आधार पर, वेंडर न्यूट्रल एपीआई के बारे में जानकारी देने वाला फ़ॉर्मैट बनाने, उसे बेहतर बनाने, और उसे प्रमोट करने पर फ़ोकस करना है." OpenAPI पहल के बारे में ज़्यादा जानकारी के लिए, https://openapis.org पर जाएं.

RESTful API के बारे में जानकारी देने के लिए, OpenAPI दस्तावेज़ स्टैंडर्ड फ़ॉर्मैट का इस्तेमाल करता है. OpenAPI दस्तावेज़ को मशीन से आसानी से पढ़ा और समझा जा सकता है, लेकिन इसे JSON या YAML फ़ॉर्मैट में लिखा गया है. इसे इंसान आसानी से पढ़ और समझ सकते हैं. OpenAPI स्पेसिफ़िकेशन, एपीआई के बेस पाथ, पाथ और क्रिया, हेडर, क्वेरी पैरामीटर, कॉन्टेंट के टाइप, रिस्पॉन्स मॉडल वगैरह जैसे एलिमेंट की औपचारिक जानकारी देने की सुविधा देता है. इसके अलावा, आम तौर पर, एपीआई दस्तावेज़ जनरेट करने के लिए OpenAPI दस्तावेज़ का इस्तेमाल किया जाता है.

यहां OpenAPI दस्तावेज़ से एक फ़्रैगमेंट दिया गया है. इसमें, Apigee के आसान हैलो वर्ल्ड वाले सैंपल के बारे में बताया गया है. ज़्यादा जानकारी के लिए, OpenAPI की खास जानकारी को यहां देखें GitHub.

openapi: 3.0.0
info:
  description: OpenAPI Specification for the Apigee mock target service endpoint.
  version: 1.0.0
  title: Mock Target API
paths:
  /:
    get:
      summary: View personalized greeting
      operationId: View a personalized greeting
      description: View a personalized greeting for the specified or guest user.
      parameters:
        - name: user
          in: query
          description: Your user name.
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Success
  /help:
    get:
      summary: Get help
      operationId: Get help
      description: View help information about available resources in HTML format.
      responses:
        "200":
          description: Success
...

OpenAPI की खास बातों के बारे में जानकारी के कई बेहतरीन स्रोत मौजूद हैं. OpenAPI इनिशिएटिव साइट पर जाकर शुरुआत की जा सकती है. इस साइट पर आपको खास जानकारी, ब्लॉग, और OpenAPI की खास बातों के लिंक मिलेंगे. स्कीमा एलिमेंट और डेटा टाइप के बारे में ज़्यादा जानकारी के लिए, स्पेसिफ़िकेशन देखें.

ऐसे कई JSON और YAML उदाहरण OpenAPI दस्तावेज़ हैं जिन्हें यहां से डाउनलोड किया जा सकता है OpenAPI स्पेसिफ़िकेशन का डेटा स्टोर करने की जगह.

ग्राफ़क्यूएल स्कीमा क्या है?

GraphQL स्कीमा आपके एपीआई में उपलब्ध डेटा के बारे में बताता है, ताकि क्लाइंट क्वेरी कर सके.

ग्राफ़क्यूएल को इस्तेमाल करने के ये फ़ायदे हैं:

  • एक ही एंडपॉइंट से किसी ऑपरेशन के लिए सभी फ़ील्ड को ऐक्सेस किया जा सकता है
  • बेहतरीन क्वेरी लैंग्वेज को स्कीमा डेफ़िनिशन लैंग्वेज कहा जाता है. इसकी मदद से, अपनी ज़रूरत के हिसाब से डेटा को ऐक्सेस किया जा सकता है. इससे डेटा को ओवर-फ़ेच या अंडर-फ़ेचिंग से रोका जा सकता है
  • क्वेरी की प्रोसेसिंग एक साथ होती है

GraphQL के बारे में ज़्यादा जानने के लिए, graphql.org पर जाएं.

नीचे दिए गए उदाहरण में ग्राफ़क्यूएल स्कीमा का उदाहरण दिया गया है. इसमें डेटा एंट्री पॉइंट (क्वेरी टाइप), लिखने के लिए उपलब्ध कार्रवाइयां (म्यूटेशन टाइप), और डेटा टाइप के बारे में बताया गया है.

type Query {
  Greeting: String
  students: [Student]
}
type Mutation {
  createStudent(firstName: String!, lastName: String!): Student!
}
type Subscription {
  newStudent: Student!
}
type Student {
  Id: ID!
  firstName: String!
  lastName: String!
  password: String!
  collegeId: String!
}

JSON पेलोड के तौर पर अपनी ज़रूरत का सटीक डेटा दिखाने के लिए, ग्राफ़QL स्कीमा पर क्वेरी चलाई जा सकती है.

ग्राफ़क्यूएल क्वेरी और उसके नतीजे

अगर मैं किसी दस्तावेज़ में बदलाव करूं, तो क्या होगा?

हर OpenAPI या GraphQL दस्तावेज़, एपीआई की पूरी लाइफ़साइकल के दौरान सत्य के स्रोत के तौर पर काम करता है. डेवलपमेंट से लेकर पब्लिश करने और मॉनिटर करने तक, एपीआई के लाइफ़साइकल के हर चरण में एक ही दस्तावेज़ का इस्तेमाल किया जाता है.

जब किसी दस्तावेज़ में बदलाव किया जाता है या उसे मिटाया जाता है, तो इसका असर नीचे जाता है:

  • किसी दस्तावेज़ में बदलाव करने पर, आपको उससे जुड़े आर्टफ़ैक्ट में मैन्युअल तरीके से बदलाव करना होगा. इसमें, एपीआई प्रॉक्सी और ऐसे एपीआई प्रॉडक्ट शामिल हैं जिनमें इसके रिसॉर्स दिखते हैं. साथ ही, आपको दस्तावेज़ में लागू किए गए बदलावों को दिखाने के लिए, एपीआई के रेफ़रंस दस्तावेज़ को फिर से जनरेट करना होगा.
  • अगर किसी दस्तावेज़ को मिटाया जाता है, तो आपको उससे जुड़े आर्टफ़ैक्ट को मैन्युअल तरीके से मिटाना होगा. इसमें एपीआई प्रॉक्सी भी शामिल है. साथ ही, एपीआई वाले अन्य प्रॉडक्ट में बदलाव करके, उससे जुड़े संसाधनों को मिटाना होगा. साथ ही, दस्तावेज़ और उसके संसाधनों को हटाने की जानकारी दिखाने के लिए, एपीआई के रेफ़रंस दस्तावेज़ को फिर से जनरेट करना होगा.

किसी OpenAPI दस्तावेज़ से एपीआई प्रॉक्सी बनाने पर क्या होता है?

Edge में, अपने OpenAPI दस्तावेज़ों से अपनी एपीआई प्रॉक्सी बनाई जा सकती हैं. सिर्फ़ कुछ क्लिक में, आपको अपने-आप जनरेट हुए पाथ, पैरामीटर, कंडिशनल फ़्लो, और टारगेट एंडपॉइंट के साथ एक एपीआई प्रॉक्सी मिलेगी. इसके बाद, OAuth सुरक्षा, दर को सीमित करने, और कैश मेमोरी जैसी सुविधाएं जोड़ी जा सकती हैं.

यहां दिए गए सेक्शन के मुताबिक, किसी OpenAPI दस्तावेज़ से एपीआई प्रॉक्सी बनाई जा सकती है:

अपने एपीआई को पब्लिश करने के दौरान, एपीआई रेफ़रंस दस्तावेज़ जनरेट करने के लिए, OpenAPI दस्तावेज़ का स्नैपशॉट लिया जाता है. वह स्नैपशॉट, विशिष्टता स्टोर में विवरण दस्तावेज़ के विशिष्ट संशोधन को दिखाता है.