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

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

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

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

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

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

«ابتکار OpenAPI (OAI) بر ایجاد، تکامل و ترویج یک قالب توصیف API بی‌طرف از فروشنده بر اساس مشخصات Swagger متمرکز است.» برای اطلاعات بیشتر در مورد ابتکار OpenAPI، به https://openapis.org مراجعه کنید.

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

در اینجا بخشی از یک سند OpenAPI آمده است که نمونه ساده hello world از 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 دانلود کنید.

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

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

مزایای استفاده از 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!
}

شما می‌توانید از طرح GraphQL کوئری بگیرید تا داده‌های دقیقی که نیاز دارید را به عنوان یک JSON payload برگردانید.

اگر سندی را تغییر دهم چه اتفاقی می‌افتد؟

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

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

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

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

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

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

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

وقتی API خود را منتشر می‌کنید ، از سند OpenAPI یک snapshot می‌گیرید تا مستندات مرجع API را ایجاد کنید. آن snapshot نشان‌دهنده‌ی یک نسخه خاص از سند توضیحات در spec store است.