مروری بر طراحی API

شما در حال مشاهده اسناد Apigee Edge هستید.
به مستندات Apigee X بروید . اطلاعات

در مرحله طراحی، الزامات API خود را تعریف می کنید. به عنوان یک طراح API، خدماتی را که می‌خواهید در معرض دید مصرف‌کنندگان قرار دهید، برنامه‌ریزی می‌کنید و APIهایی را برای دسترسی به آن خدمات طراحی می‌کنید. شما یکی از اسناد زیر را برای ثبت نیازهای API خود ایجاد می کنید:

• یک سند OpenAPI
• یک طرحواره GraphQL

بخش های زیر اطلاعات بیشتری در مورد اسناد OpenAPI و GraphQL و نقش آنها در چرخه حیات API شما ارائه می دهد. برای مقایسه دو گزینه طراحی API، به مقایسه REST و GraphQL در این پست وبلاگ مراجعه کنید.

مشخصات OpenAPI چیست؟

"ابتکار OpenAPI (OAI) بر ایجاد، تکامل و ترویج فرمت توضیحات API خنثی فروشنده بر اساس مشخصات Swagger متمرکز شده است." برای اطلاعات بیشتر درباره OpenAPI Initiative، به https://openapis.org مراجعه کنید.

یک سند OpenAPI از یک قالب استاندارد برای توصیف یک API RESTful استفاده می کند. یک سند OpenAPI که در قالب JSON یا YAML نوشته شده است، قابل خواندن با ماشین است، اما خواندن و درک آن برای انسان نیز آسان است. مشخصات OpenAPI توصیف رسمی عناصر یک API مانند مسیر اصلی، مسیرها و افعال، هدرها، پارامترهای پرس و جو، انواع محتوا، مدل‌های پاسخ و موارد دیگر را امکان‌پذیر می‌سازد. علاوه بر این، یک سند OpenAPI معمولا برای تولید اسناد API استفاده می شود.

در اینجا بخشی از یک سند 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 Initiative است که در آن مرورهای کلی، وبلاگ ها و پیوندهایی به مشخصات OpenAPI را خواهید یافت. برای توصیف دقیق عناصر طرحواره و انواع داده ها به مشخصات مراجعه کنید.

تعدادی از اسناد OpenAPI نمونه JSON و YAML وجود دارد که می توانید از مخزن OpenAPI Specification دانلود کنید.

طرحواره GraphQL چیست؟

یک طرحواره GraphQL داده های موجود در API شما را برای یک کلاینت برای پرس و جو توصیف می کند.

مزایای استفاده از GraphQL عبارتند از:

• یک نقطه پایانی واحد دسترسی به تمام فیلدها را برای یک عملیات معین فراهم می کند
• زبان پرس و جو قدرتمند به نام Schema Definition Language به شما امکان می دهد دقیقاً به داده هایی که نیاز دارید دسترسی داشته باشید و از واکشی بیش از حد یا کم واکشی داده ها جلوگیری کنید.
• پردازش پرس و جوها به صورت موازی انجام می شود

برای اطلاعات بیشتر در مورد GraphQL، به graphql.org مراجعه کنید.

در زیر نمونه ای از طرحواره GraphQL ارائه می شود که نقطه ورود داده (نوع Query)، عملیات نوشتن موجود (نوع جهش) و انواع داده را تعریف می کند.

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!
}

می‌توانید از طرح GraphQL پرس و جو کنید تا داده‌های دقیق مورد نیاز خود را به عنوان یک بار JSON بازگردانید.

اگر سندی را اصلاح کنم چه اتفاقی می افتد؟

هر سند OpenAPI یا GraphQL به عنوان منبع حقیقت در طول چرخه حیات API عمل می کند. سند یکسان در هر مرحله از چرخه حیات API، از توسعه تا انتشار و نظارت استفاده می‌شود.

هنگامی که یک سند را ویرایش یا حذف می‌کنید، در نهایت تأثیر می‌گذارد:

• اگر سندی را ویرایش می‌کنید، باید مصنوعات مرتبط از جمله پروکسی API و هر محصول API را که منابع آن را در معرض دید قرار می‌دهد، به صورت دستی ویرایش کنید و اسناد مرجع API را برای انعکاس تغییرات اعمال‌شده در سند بازسازی کنید.
• اگر سندی را حذف می‌کنید، باید مصنوعات مرتبط از جمله پروکسی API را به صورت دستی حذف کنید و محصولات API را برای حذف منابع مرتبط ویرایش کنید، و اسناد مرجع API را دوباره ایجاد کنید تا حذف سند و منابع آن را منعکس کند.

وقتی یک پروکسی API از یک سند OpenAPI ایجاد می کنم چه اتفاقی می افتد؟

در Edge، می توانید پروکسی های API خود را از اسناد OpenAPI خود ایجاد کنید. تنها با چند کلیک، یک پروکسی API با مسیرها، پارامترها، جریان های شرطی و نقاط پایانی هدف خواهید داشت که به طور خودکار تولید می شوند. سپس، می‌توانید ویژگی‌هایی مانند امنیت OAuth، محدود کردن نرخ و حافظه پنهان را اضافه کنید.

همانطور که در بخش های زیر توضیح داده شده است، می توانید یک پروکسی API از یک سند OpenAPI ایجاد کنید:

• از لیست مشخصات، همانطور که در ایجاد یک پراکسی API از یک مشخصات در لیست مشخصات توضیح داده شده است. توجه : لیست مشخصات در Classic Edge موجود نیست.
• از مدیر پراکسی‌های API با فراخوانی Build Proxy Wizard و انتخاب ایجاد پروکسی API از یک سند OpenAPI، همانطور که در استفاده از مشخصات OpenAPI برای تولید پراکسی توضیح داده شده است.

هنگامی که API خود را منتشر می کنید، یک عکس فوری از سند OpenAPI می گیرید تا اسناد مرجع API را ایجاد کنید. آن عکس فوری بازبینی خاصی از سند توضیحات در فروشگاه مشخصات را نشان می دهد.