راهنمای استفاده از API

به جز مراحل احراز هویت، بقیه‌ی امکانات API از طریق کارگزاری در‌دسترس هستند که با زبان پرس‌و‌جوی GraphQL کار می‌کند. برای پرس‌و‌جو (مثلاً گرفتن لیست تیکت‌ها) یا ایجاد تغییر روی داده‌ها (مثلاً ایجاد یک تیکت)، شما نیاز دارید یک عبارت به عنوان Query به سرور زرین‌پال با URL زیر ارسال کنید:

https://next.zarinpal.com/api/v4/graphql

این درخواست با استفاده از متد POST و با نوع محتوای application/json ارسال می‌شود. کد زیر، نمونه‌ی ارسال یک کوئری با ابزار cURL نشان می‌دهد:

$ curl 'https://next.zarinpal.com/api/v4/graphql/' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  --data-binary '{"query":"query { Application { application, platform } }","variables":null}'

در نمونه‌ی بالا، با توکن {ACCESS_TOKEN} کوئری query { Application { application, platform } } اجرا می‌شود.

در ادامه، خلاصه‌ای از چگونگی نوشتن پرس‌و‌جو با GraphQL آورده شده. در بخش شِمای مستندات، می‌توانید لیستی از پرس‌و‌جوها و تغییرهایی که می‌توانید ایجاد کنید را پیدا کنید.

نوشتن پرس‌و‌جوی GraphQL

پرس‌وجوی شما، می‌تواند از نوع query یا mutation باشد.

• query - اطلاعاتی را می‌خواند و تغییری ایجاد نمی‌کند
• mutation - اطلاعاتی را تغییر می‌دهد و نتایج تغییرات را برمی‌گرداند

در ابتدا، نوع پرس‌و‌جوی خودتان را مشخص می‌کنید:

query {
}

یا برای تغییر:

mutation {
}

سپس باید نام عمل پرس‌و‌جو یا تغییر را تعیین کنید، برای مثال می‌خواهیم لیست کوئری‌های کاربر را بگیریم:

query {
  Tickets {
  }
}

این کوئری هنوز صحیح نیست، چرا که سرور نیاز دارد که بداند شما به چه فیلدهایی لازم دارید. مثلاً ما فیلدهای id و status را لازم داریم:

query {
  Tickets {
    id
    status
  }
}

نکته: برای نوشتن پرس‌و‌جوها در یک خط، بین فیلدها به جای n\ باید , قرار دهید، مثلاً:

query { Tickets { id, status } }

با ارسال این پرس‌و‌جو به سرور، پاسخی مشابه پاسخ زیر دریافت می‌کنید:

{
  "data": {
    "Tickets": [
      {
        "id": "139805250316",
        "status": "CLOSED"
      },
      {
        "id": "139805250335",
        "status": "CLOSED"
      }
    ]
  }
}

پاس‌دادن پارامتر

برخی از پرس‌و‌جوها و هم‌چنین همه‌ی تغییرها (Mutation) نیاز به پارامترهای ورودی دارند. مثلاً در مثال بالا، شما می‌توانید تعیین کنید که حداکثر ۱۵ تیکت به شما برگردانده شود:

query {
  Tickets(limit: 15) {
    id
    status
  }
}

لیست پارامترها، فیلدهای بازگشتی و نوع آن‌ها را در شِما می‌توانید ببینید.

و یا می‌توانید تعیین کنید که از ۱۰ تیکت اول صرف‌نظر شود:

query {
  Tickets(limit: 15, offset: 10) {
    id
    status
  }
}

اما بیایید ایجاد یک تغییر را بررسی کنیم:

mutation {
  CardAdd(pan: "1111222233334444", expired_at: "2020-02-05 00:00:00") {
    id
  }
}

اولین چیزی که باید به آن دقت کرد، تفاوت نوع ریشه‌ی پرس‌و‌جو (Root Type) است. در مثال‌های قبلی، چون نیازی به نوشتن داده‌ی جدیدی نداشتیم، از query استفاده می‌کردیم، اما در این مثال، می‌خواهیم یک کارت جدید اضافه کنیم، پس به mutation نیاز داریم.

در واقع انواع پرس‌و‌جوهایی که در دسترس شما هستند، یا از نوع query هستند یا mutation؛ برای استفاده از هر کدام باید Root Type عبارت پرس‌و‌جوی خودتان را مطابق آن قرار دهید.

در پرس‌و‌جوی بالا، در صورت موفقیت‌آمیز بودن عملیات، id کارت جدید برگردانده می‌شود. در واقع Return Type عملیات CardAdd از نوع Card است، بنابراین باید تعیین کنید که دقیقاً کدام فیلدهای شیٔ Card ساخته‌شده را لازم دارید. در قسمت بعدی درمورد شیٔ‌ها توضیح داده شده است.

نوع‌ها در GraphQL

به طور کلی، GraphQL سه نوع داده وجود دارد:

• Object
• Scalar
• Enum

نوع Scalar همان داده‌های معمول هستند که یکی از String، Int، DateTime، ID یا Boolean هستند. نوع Object یا شیٔ مانند بیشتر زبان‌های برنامه‌نویسی، از تعدادی عضو تشکیل شده که عضوهای آن را فیلد (Field) صدا می‌زنیم. هر فیلد از یک Key و یک Value تشکیل شده. Key حتماً یک رشته است که در میان بقیه‌ی فیلدهای دیگر یگانه است و Value هم از نوع Scalar یا Object یا لیست است. در GraphQL، نوع شیٔ با کلیدواژه‌ی type در شِما تعریف می‌شود، مثلاً:

type Post {
  id: ID!
  title: String!
  content: String
  comments: [Comment!]
}

علامت ! در جلوی نوع فیلد به این معنی است که مقدار فیلد هیچ‌گاه Null نخواهد شد.

هم‌چنین GraphQL از نوع دیگری به نام List پشتیبانی می‌کند، یعنی پاسخ پرس‌و‌جو یا تغییر شما، می‌تواند یک لیست از چندین شیٔ یا مقدار اسکالار باشد، مثلاً اگر شِما به این شکل باشد:

query {
  Tickets: [Ticket!]!
}

کد بالا نشان می‌دهد که عملیاتی به نام Tickets، مجموعه‌ای از اشیای Ticket برمی‌گرداند. علامت ! جلوی Ticket، به این معنی است که هیچ‌کدام از اعضای این لیست، Null نیستند. (در حال حاضر تمام لیست‌های GrpahQL باید به این گونه باشند و مقدار Null برای اعضا پشتیبانی نمی‌شود.) علامت ! جلوی براکت، به این معنی است که این لیست «حتماً» حداقل یک عضو دارد. اگر این علامت نباشد، به این معنی است که پاسخ عملیات Tickets می‌تواند یک لیست خالی ([]) باشد.

مقادیر اسکالار هم می‌توانند به صورت لیست ارسال شوند، مثلاً اگر شِما به این شکل باشد:

query {
  Numbers: [Int!]
}

یک لیست که هر عضو آن یک Int است در پاسخ آن ارسال می‌شود.

دقت کنید که داخل هر شیٔ هم می‌تواند یک فیلد با نوع لیست هم باشد.

برای اطلاعات بیشتر درمورد نوشتن شِما و پرس‌و‌جوهای GraphQL می‌توانید به مستندات آن (opens new window) مراجعه کنید.

محیط اجرا

شما می‌توانید در محیط اجرای GraphiQL (opens new window) پرس‌و‌جوهای‌تان را تست کنید.