API ডিজাইন সম্পর্কে এক ঝলকে

আপনি Apigee Edge ডকুমেন্টেশন দেখছেন।
Apigee X ডকুমেন্টেশন দেখুন। তথ্য

ডিজাইন ধাপে, আপনার API-এর প্রয়োজনীয়তা নির্ধারণ করেন। API ডিজাইনার হিসেবে, আপনি গ্রাহকদের কাছে প্রকাশ করতে চান এমন পরিষেবাগুলি প্ল্যান করেন এবং সেইসব পরিষেবা অ্যাক্সেস করার জন্য API ডিজাইন করেন। আপনার API সংক্রান্ত প্রয়োজনীয়তা ক্যাপচার করতে, নিম্নলিখিত ডকুমেন্টগুলির মধ্যে একটি তৈরি করুন:

  • OpenAPI ডকুমেন্ট
  • GraphQL স্কিমা

নিচের বিভাগগুলি OpenAPI এবং GraphQL ডকুমেন্ট এবং আপনার API-এর লাইফসাইকেলে তাদের ভূমিকা সম্পর্কে আরও তথ্য প্রদান করে। দুটি API ডিজাইন বিকল্পের তুলনা দেখতে, এই ব্লগ পোস্টে REST ও GraphQL-এর তুলনা দেখুন।

OpenAPI স্পেসিফিকেশন কী?


"OpenAPI ইনিশিয়েটিভ (OAI) হল এমন একটি সংস্থা যা Swagger স্পেসিফিকেশনের উপর ভিত্তি করে ভেন্ডর নিউট্রাল API বিবরণ ফর্ম্যাট তৈরি, উন্নত ও প্রচার করার উপর ফোকাস করে।" OpenAPI ইনিশিয়েটিভ সম্পর্কে আরও তথ্য পেতে, https://openapis.org দেখুন।

OpenAPI ডকুমেন্ট RESTful API-এর বর্ণনা দেওয়ার জন্য একটি স্ট্যান্ডার্ড ফর্ম্যাট ব্যবহার করে। JSON বা YAML ফর্ম্যাটে লেখা, একটি OpenAPI ডকুমেন্ট মেশিনের মাধ্যমে পড়ার উপযুক্ত, তবে এটি মানুষও সহজে পড়তে ও বুঝতে পারে। OpenAPI স্পেসিফিকেশন, API-এর এলিমেন্ট যেমন, এর বেস পাথ, পাথ ও ভার্ব, হেডার, কোয়েরি প্যারামিটার, কন্টেন্টের ধরন, উত্তর মডেল ও আরও অনেক কিছুর ফর্মাল বিবরণ দেয়। এছাড়াও, API ডকুমেন্টেশন তৈরি করতে সাধারণত OpenAPI ডকুমেন্ট ব্যবহার করা হয়।

Apigee-এর সাধারণ হ্যালো ওয়ার্ল্ড স্যাম্পেল বর্ণনা করে এমন OpenAPI ডকুমেন্ট থেকে নেওয়া একটি ফ্র্যাগমেন্ট এখানে দেওয়া হল। আরও তথ্যের জন্য, 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 ইনিশিয়েটিভ সাইটটি ভাল জায়গা, যেখানে আপনি OpenAPI স্পেসিফিকেশন-এর ওভারভিউ, ব্লগ ও লিঙ্ক পাবেন। স্কিমা এলিমেন্ট ও ডেটার ধরন সম্পর্কে বিস্তারিত বিবরণের জন্য স্পেসিফিকেশন দেখুন।

JSON এবং YAML-এর উদাহরণ সহ OpenAPI ডকুমেন্টের সংখ্যা অনেক, যা আপনি OpenAPI স্পেসিফিকেশন রিপোজিটরি থেকে ডাউনলোড করতে পারবেন।

GraphQL স্কিমা কী?

GraphQL স্কিমা হল এমন একটি বিবরণ যা ক্লায়েন্টকে কোয়েরি করার জন্য আপনার API-তে উপলভ্য ডেটা সম্পর্কে জানায়।

GraphQL ব্যবহার করার সুবিধাগুলির মধ্যে এগুলি অন্তর্ভুক্ত:

  • একটি এন্ডপয়েন্ট কোনও নির্দিষ্ট অপারেশনের জন্য সব ফিল্ডে অ্যাক্সেস প্রদান করে
  • Schema Definition Language নামের শক্তিশালী কোয়েরি ভাষা আপনাকে ঠিক সেই ডেটা অ্যাক্সেস করতে দেয় যা আপনার প্রয়োজন, এর ফলে ডেটা বেশি বা কম ফেচ করা আটকানো যায়
  • কোয়েরি প্রসেস করার কাজটি প্যারালাল প্রসেসে হয়

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 কোয়েরি ও ফলাফল

আমি কোনও ডকুমেন্ট পরিবর্তন করলে কী হবে?

API লাইফসাইকেল জুড়ে প্রতিটি OpenAPI বা GraphQL ডকুমেন্ট সোর্স অফ ট্রুথ হিসেবে কাজ করে। API লাইফসাইকেলের প্রতিটি ধাপে একই ডকুমেন্ট ব্যবহার করা হয়, ডেভেলপমেন্ট থেকে শুরু করে প্রকাশ করা ও মনিটর করা পর্যন্ত।

আপনি কোনও ডকুমেন্ট এডিট বা মুছে দিলে, এর প্রভাব পরে:

  • আপনি কোনও ডকুমেন্ট এডিট করলে, আপনাকে API প্রক্সি ও এর রিসোর্স এক্সপোজ করা API প্রোডাক্ট সহ সংশ্লিষ্ট আর্টিফ্যাক্ট ম্যানুয়ালি এডিট করতে হবে এবং ডকুমেন্টে প্রয়োগ করা পরিবর্তনগুলি দেখাতে API রেফারেন্স ডকুমেন্টেশন আবার তৈরি করতে হবে।
  • আপনি কোনও ডকুমেন্ট মুছে দিলে, আপনাকে API প্রক্সি সহ সংশ্লিষ্ট আর্টিফ্যাক্ট ম্যানুয়ালি মুছে ফেলতে হবে এবং সংশ্লিষ্ট রিসোর্স মুছে ফেলার জন্য যেকোনও API প্রোডাক্ট এডিট করতে হবে এবং ডকুমেন্ট ও এর রিসোর্স মুছে ফেলার বিষয়টি দেখাতে API রেফারেন্স ডকুমেন্টেশন আবার তৈরি করতে হবে।

OpenAPI ডকুমেন্ট থেকে API প্রক্সি তৈরি করলে কী হয়?

Edge-এ, আপনি OpenAPI ডকুমেন্ট থেকে API প্রক্সি তৈরি করতে পারবেন। মাত্র কয়েকটি ক্লিক করেই, আপনি পাথ, প্যারামিটার, কন্ডিশনাল ফ্লো ও অটোমেটিক জেনারেট হওয়া টার্গেট এন্ডপয়েন্ট সহ API প্রক্সি পেয়ে যাবেন। তারপরে, আপনি OAuth নিরাপত্তা, রেট লিমিটিং এবং ক্যাশিংয়ের মতো ফিচার যোগ করতে পারবেন।

আপনি OpenAPI ডকুমেন্ট থেকে API প্রক্সি তৈরি করতে পারবেন, যা নিম্নলিখিত বিভাগে বর্ণনা করা হয়েছে:

আপনি API প্রকাশ করলে, API রেফারেন্স ডকুমেন্ট তৈরি করতে OpenAPI ডকুমেন্টের একটি স্ন্যাপশট নেন। সেই স্ন্যাপশটটি স্পেক স্টোরে থাকা বিবরণ ডকুমেন্টের একটি নির্দিষ্ট রিভিশনকে উপস্থাপন করে।