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

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

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

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

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

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


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

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

यहां OpenAPI दस्तावेज़ का एक फ़्रैगमेंट दिया गया है. इसमें Apigee के सामान्य Hello World सैंपल के बारे में बताया गया है. ज़्यादा जानकारी के लिए, 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 साइट पर जाएं. यहां आपको खास जानकारी, ब्लॉग, और OpenAPI Specification के लिंक मिलेंगे. स्कीमा एलिमेंट और डेटा टाइप के बारे में ज़्यादा जानकारी पाने के लिए, स्पेसिफ़िकेशन देखें.

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

GraphQL स्कीमा क्या होता है?

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

GraphQL का इस्तेमाल करने के ये फ़ायदे हैं:

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

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

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

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 पेलोड के तौर पर पाने के लिए, GraphQL स्कीमा को क्वेरी किया जा सकता है.

GraphQL क्वेरी और नतीजे

किसी दस्तावेज़ में बदलाव करने पर क्या होता है?

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

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

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

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

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

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

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