مشخصهٔ Arazzo چیست؟

فراخوانی‌های API به‌ندرت به‌تنهایی انجام می‌شوند. بسیار رایج‌تر است که یک تابع برنامه‌نویسی به مجموعه‌ای از فراخوانی‌های API نیاز داشته باشد که به آن «گردش کار API» (API workflow) می‌گویند. برای کمک به توصیف این موقعیت‌ها، OpenAPI Initiative مشخصهٔ جدیدی به نام Arazzo منتشر کرده که دقیقاً برای پوشش گردش کارهای API طراحی شده است.

در API Days ۲۰۲۴ هلسینکی، فرانک کیل‌کامینز از شرکت SmartBear مشخصهٔ Arazzo را معرفی کرد و توضیح داد که این مشخصه چگونه گروهی از APIها و روابط بین آن‌ها را توصیف می‌کند. ما مشخصه را بررسی کرده‌ایم و یک راهنمای کوتاه و مقدماتی برای شروع کار با این استاندارد جدید API آماده کرده‌ایم.

مقدمه‌ای بر مشخصهٔ Arazzo

مشخصهٔ Arazzo: یک «تاروپود» برای گردش کارهای API قطعی و تعیین‌شده.

مشخصهٔ Arazzo راه‌حلی برای افزودن لایه‌ای از انتزاع ارائه می‌دهد تا مجموعه‌ای از فراخوانی‌های API را تعریف کند. همچنین وابستگی‌های آن‌ها را توصیف می‌کند که می‌توانند به هم متصل شوند تا نتیجهٔ خاصی تولید کنند. مشخصهٔ Arazzo هم برای ماشین قابل خواندن است و هم برای انسان. همین ویژگی ماشین‌خوان بودن، اکوسیستم غنی از ابزارها و قابلیت‌ها را ممکن می‌سازد.

آرازو (Arazzo) طوری طراحی شده که تعویض APIها در یک گردش کار سریع و آسان باشد. همچنین برای ساده‌سازی مستندات بزرگ و دست‌وپاگیر API ساخته شده است. به همین دلیل، استفاده از Arazzo می‌تواند هم تجربهٔ کاربری (UX) و هم تجربهٔ توسعه‌دهنده (DX) را بهبود بخشد.

درون مشخصهٔ Arazzo

آرازو (Arazzo) تفاوت زیادی با یک مشخصهٔ API معمولی ندارد. یک فایل مشخصهٔ Arazzo شامل تمام اطلاعات مربوط به یک گردش کار API به فرمت JSON یا YAML است. اگر خودتان Arazzo را امتحان می‌کنید، بهترین روش این است که فایل را arazzo.json یا arazzo.yaml نام‌گذاری کنید.

هستهٔ مشخصهٔ Arazzo، شیء مشخصهٔ Arazzo (Arazzo Specification Object) است. مانند مشخصهٔ OpenAPI، این شیء مشخص می‌کند که از کدام نسخهٔ Arazzo استفاده می‌شود. همچنین شامل متادیتا دربارهٔ گردش کار است که ابزارها می‌توانند از آن استفاده کنند. فیلد sourceDescriptions فهرستی از توصیفات منبع (مثلاً توصیفات OpenAPI) است. بعد از آن شیء workflows قرار دارد که تمام گردش کارهای مورد استفاده در مشخصه را شامل ورودی‌ها، وابستگی‌ها و گام‌های جداگانه فهرست می‌کند. در نهایت شیء components شامل اسکیماهایی است که در توصیف Arazzo به کار می‌روند.

نمونه‌ای از شیء مشخصهٔ Arazzo:

arazzo: 1.0.0
info:
  title: A pet purchasing workflow
  summary: This Arazzo Description showcases the workflow for how to purchase a pet through a sequence of API calls
  description: |
      This Arazzo Description walks you through the workflow and steps of `searching` for, `selecting`, and `purchasing` an available pet.
  version: 1.0.1
sourceDescriptions:
- name: petStoreDescription
  url: https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml
  type: openapi

workflows:
- workflowId: loginUserAndRetrievePet
  summary: Login User and then retrieve pets
  description: This workflow lays out the steps to login a user and then retrieve pets
  inputs:
      type: object
      properties:
          username:
              type: string
          password:
              type: string
  steps:
  - stepId: loginStep
    description: This step demonstrates the user login step
    operationId: loginUser
    parameters:
      # parameters to inject into the loginUser operation (parameter name must be resolvable at the referenced operation and the value is determined using {expression} syntax)
      - name: username
        in: query
        value: $inputs.username
      - name: password
        in: query
        value: $inputs.password
    successCriteria:
      # assertions to determine step was successful
      - condition: $statusCode == 200
    outputs:
      # outputs from this step
      tokenExpires: $response.header.X-Expires-After
      rateLimit: $response.header.X-Rate-Limit
      sessionToken: $response.body
  - stepId: getPetStep
    description: retrieve a pet by status from the GET pets endpoint
    operationPath: '{$sourceDescriptions.petStoreDescription.url}#/paths/~1pet~1findByStatus/get'
    parameters:
      - name: status
        in: query
        value: 'available'
      - name: Authorization
        in: header
        value: $steps.loginStep.outputs.sessionToken
    successCriteria:
      - condition: $statusCode == 200
    outputs:
      # outputs from this step
      availablePets: $response.body
  outputs:
      available: $steps.getPetStep.outputs.availablePets

درون شیء Workflows

بیایید لحظه‌ای فقط به بخش workflows توجه کنیم که بخش عمدهٔ مشخصهٔ Arazzo را تشکیل می‌دهد.

workflows:
- workflowId: loginUserAndRetrievePet
  summary: Login User and then retrieve pets
  description: This workflow lays out the steps to login a user and then retrieve pets
  inputs:
      type: object
      properties:
          username:
              type: string
          password:
              type: string
  steps:
  - stepId: loginStep
    description: This step demonstrates the user login step
    operationId: loginUser
    parameters:
      # parameters to inject into the loginUser operation (parameter name must be resolvable at the referenced operation and the value is determined using {expression} syntax)
      - name: username
        in: query
        value: $inputs.username
      - name: password
        in: query
        value: $inputs.password
    successCriteria:
      # assertions to determine step was successful
      - condition: $statusCode == 200
    outputs:
      # outputs from this step
      tokenExpires: $response.header.X-Expires-After
      rateLimit: $response.header.X-Rate-Limit
      sessionToken: $response.body
  - stepId: getPetStep
    description: retrieve a pet by status from the GET pets endpoint
    operationPath: '{$sourceDescriptions.petStoreDescription.url}#/paths/~1pet~1findByStatus/get'
    parameters:
      - name: status
        in: query
        value: 'available'
      - name: Authorization
        in: header
        value: $steps.loginStep.outputs.sessionToken
    successCriteria:
      - condition: $statusCode == 200
    outputs:
      # outputs from this step
      availablePets: $response.body
  outputs:
      available: $steps.getPetStep.outputs.availablePets

ابتدا می‌بینیم که این گردش کار loginUserAndRetrievePet نام دارد. سپس خلاصه و توضیح کوتاهی دربارهٔ عملکرد آن آمده است. بخش inputs بعدی است که به کاربر می‌گوید چه داده‌هایی انتظار می‌رود و فرمت آن‌ها چیست.

بخش steps بخش اصلی شیء workflows را تشکیل می‌دهد. هر گام شامل توضیح و خلاصه، پارامترها، معیارهای موفقیت و در نهایت خروجی‌های موفق است. شیء outputs در انتهای گردش کار مشخص می‌کند که پس از تکمیل موفق یک گام چه اتفاقی می‌افتد.

شیء steps فقط برای تأیید موفقیت نیست؛ متغیرهای خروجی گردش کار حتی اگر خارج از پارامترها باشند هم می‌توانند منتقل شوند و به گردش کارهای دیگر یا سیستم لاگ‌گیری ارسال شوند.

آرازو (Arazzo) چگونه تجربهٔ توسعه‌دهنده را بهبود می‌دهد؟

با پیچیده‌تر شدن APIها، مستندات آن‌ها بیش از حد سنگین و دشوار برای درک می‌شود و API شکننده می‌شود زیرا وابستگی‌های مختلفی برای رسیدن به یک هدف وجود دارد. بسیاری از این رفتارها پیش از انتشار Arazzo کاملاً مستند نبودند.

اغلب بین تولیدکنندگان و مصرف‌کنندگان API فاصله وجود دارد. توسعه‌دهندگان API معمولاً مشخصهٔ خام را در فرآیند onboarding به مصرف‌کنندگان می‌دهند که معمولاً به‌هم‌ریخته و سخت‌خوان است. مستندات رسمی هم خیلی زود قدیمی می‌شوند. مشخصهٔ Arazzo هر دو مشکل را همزمان حل می‌کند و مستندات تعاملی گردش کار و خودکارسازی مستندات API را ممکن می‌سازد.

اولین مزیت Arazzo برای توسعه‌دهندگان این است که فرمت آن برایشان آشناست (بسیار شبیه OpenAPI است و اغلب کنار هم ذخیره می‌شوند).

همچنین با قابلیت sourceDescriptions می‌توان کامپوننت‌های خود را تعریف کرد که باعث می‌شود گردش کارهای API بسیار کمتر شکننده و دست‌وپاگیر باشند. این ویژگی Arazzo را برای پیاده‌سازی گردش کارهای احراز هویت عالی می‌کند. مشخصه می‌تواند هر گام را با کد وضعیت HTTP خودش توصیف کند و به مصرف‌کننده کمک کند قصد تولیدکننده را دقیقاً بفهمد (بهبود چشمگیر DX).

بزرگ‌ترین مزیت DX مربوط به مدل‌های زبانی بزرگ (LLM) است. داشتن مشخصه‌ای که دقیقاً توضیح می‌دهد هر فراخوانی API چه کاری انجام می‌دهد، درک آن را برای LLMهایی مثل ChatGPT بسیار آسان‌تر می‌کند. همان‌طور که فرانک کیل‌کامینز اخیراً گفت، در حال حاضر هوش‌های مولد در ساخت یا مصرف API حدود ۸۰-۹۰٪ موفقیت دارند و بقیه اغلب توهم (hallucination) است. افزودن مستندات گردش کار به همراه مستندات API دقت را به‌طور چشمگیری افزایش می‌دهد و حتی امکان تولید API از مشخصه با GPTهای سفارشی را فراهم می‌کند.

جمع‌بندی دربارهٔ مشخصهٔ Arazzo

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

آرازو (Arazzo) همچنین پتانسیل این را دارد که APIها را بسیار کمتر شکننده و ماژولارتر و چندمنظوره‌تر کند؛ چیزی که با پیچیده‌تر شدن APIها روزبه‌روز حیاتی‌تر می‌شود. در نهایت، Arazzo قول می‌دهد دنیای کاملاً جدیدی از ابزارهای قدرتمند را باز کند که نحوهٔ کار توسعه‌دهندگان با APIها را دگرگون خواهد کرد.