نمای کلی طراحی میانای برنامه‌سازی کاربردی

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

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

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

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

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

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

سند OpenAPI از قالب استانداردی برای توصیف یک RESTful API استفاده می‌کند. سند 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 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!
}

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

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

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

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

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

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

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

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

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

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