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

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

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

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

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

OpenAPI स्पेसिफ़िकेशन क्या है?


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

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

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

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 Initiative साइट पर जाएं. यहां आपको खास जानकारी, ब्लॉग, और ओपनएपीआई स्पेसिफ़िकेशन के लिंक मिलेंगे. स्कीमा एलिमेंट और डेटा टाइप के बारे में ज़्यादा जानकारी के लिए, खास जानकारी देखें.

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

ग्राफ़QL स्कीमा क्या है?

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

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

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

ग्राफ़QL के बारे में ज़्यादा जानकारी के लिए, graphql.org देखें.

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

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 या ग्राफ़क्यूएल दस्तावेज़, एपीआई की पूरी लाइफ़साइकल के दौरान, सच्चाई के स्रोत के तौर पर काम करता है. एपीआई के लाइफ़साइकल के हर चरण में, एक ही दस्तावेज़ का इस्तेमाल किया जाता है. जैसे, डेवलपमेंट से लेकर पब्लिश करने और उसे मॉनिटर करने की प्रक्रिया.

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

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

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

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

नीचे बताए गए तरीके का इस्तेमाल करके, OpenAPI दस्तावेज़ से एपीआई प्रॉक्सी बनाई जा सकती है:

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