GraphQL API का उपयोग करना

ऑपरेशन ढूँढना

समर्थित GraphQL उपसमूह के लिए schema ही आधिकारिक स्रोत है: operation roots, नाम, arguments, input types, और enum values। विवरण उपयोग संबंधी मार्गदर्शन देते हैं, और GraphQL Explorer दोनों को दिखाता है। केवल REST वाली क्षमताओं के लिए REST API reference का उपयोग करें। ऑपरेशन नाम उन REST endpoints के अनुसार होते हैं जिन तक वे पहुँचते हैं, camelCase में। GET /history postHistory है, GET /analytics/social socialAnalytics है, POST /post createPost है।

Queries पढ़ती हैं, mutations लिखते हैं

Queries पढ़ने और validation के लिए होती हैं जो हमारी ओर कुछ नहीं बदलतीं। Mutations प्रकाशित करते हैं या state बदलते हैं, कोई कार्य शुरू करते हैं, या email भेजते हैं। Root का निर्धारण न तो REST HTTP verb से होता है और न ही किसी call की लागत से:

validatePost किसी पोस्ट को प्रकाशित किए बिना जाँचता है।
validateMedia जाँचता है कि कोई media URL पहुँच योग्य है।
generatePost एक query है क्योंकि हमारी ओर कुछ नहीं बदलता। फिर भी यह एक API call के रूप में गिना जाता है और हर बार अलग टेक्स्ट लौटाता है, इसलिए सुनिश्चित करें कि कोई client cache या automatic refetch आपकी जानकारी के बिना इसे दोहराए नहीं।
mediaUploadUrl एक mutation है क्योंकि यह आपके खाते के लिए एक upload URL बनाता है।
linkAnalytics एक mutation है क्योंकि यह email द्वारा भेजी जाने वाली रिपोर्ट का अनुरोध कर सकता है।
userBatch एक mutation है क्योंकि यह एक export job शुरू करता है।

प्रत्येक समर्थित ऑपरेशन का root पुष्टि करने के लिए Explorer या schema का उपयोग करें।

पोस्ट बनाना

createPost एक ही input argument लेता है, इसलिए पूरी पोस्ट एक object होती है:

mutation {
  createPost(input: {
    post: "Hello from GraphQL"
    platforms: [LINKEDIN]
    idempotencyKey: "post-2026-09-01-001"
  }) {
    status
    id
  }
}

Input प्रलेखित REST post endpoint को प्रतिबिंबित करता है, जिसमें प्रति-नेटवर्क option objects और वे REST रूप शामिल हैं जो एक से अधिक JSON आकार स्वीकार करते हैं:

mutation {
  createPost(input: {
    post: "New video"
    platforms: [YOUTUBE]
    mediaUrls: ["https://example.com/video.mp4"]
    idempotencyKey: "youtube-video-001"
    youTubeOptions: {
      title: "My video"
      visibility: PUBLIC
    }
  }) {
    status
    id
    postIds { platform postUrl }
  }
}

कोई पोस्ट एक नेटवर्क पर सफल और दूसरे पर विफल हो सकती है। यह request की विफलता नहीं है — त्रुटियाँ देखें।

Argument types

अधिकांश arguments सामान्य strings, numbers और booleans होते हैं। तीन मामले जानने योग्य हैं।

Enums

सीमित समर्थित सेट वाले कई string arguments GraphQL enums होते हैं, जिन्हें बिना quotes के और upper case में लिखा जाता है:

{ socialAnalytics(platforms: [INSTAGRAM, TIKTOK]) }

"instagram" नहीं। Server प्रत्येक स्वीकृत enum को अंतर्निहित REST controller द्वारा अपेक्षित सटीक मान में मैप करता है — अक्सर, लेकिन हमेशा नहीं, एक lowercase string। अमान्य enum को ऑपरेशन चलने से पहले GraphQL validation के दौरान ही अस्वीकार कर दिया जाता है, इसलिए किसी typo की आपको कोई कीमत नहीं चुकानी पड़ती। कुछ arguments का नाम विभिन्न ऑपरेशन्स में एक जैसा होता है लेकिन वे अलग-अलग मान स्वीकार करते हैं, क्योंकि endpoints वास्तव में भिन्न हैं। reviews(platform:) केवल GMB और FACEBOOK स्वीकार करता है, क्योंकि केवल इन्हीं नेटवर्क्स पर reviews होते हैं। आपके client का autocomplete प्रत्येक ऑपरेशन के लिए सही सेट दिखाएगा।

JSON scalar

कुछ arguments किसी विशिष्ट type के बजाय JSON के रूप में typed होते हैं। ऐसा वहाँ होता है जहाँ किसी मान के वास्तव में एक से अधिक आकार हो सकते हैं और कोई एक GraphQL type उसका सही-सही वर्णन नहीं कर सकता:

explainError(code:) 215 या “215” स्वीकार करता है, क्योंकि ग्राहक error codes को दोनों रूपों में रखते हैं।
createPost(input:) post और mediaUrls जैसे फ़ील्ड्स के लिए JSON का उपयोग करता है, जो साझा मान या प्रति-प्लेटफ़ॉर्म objects हो सकते हैं।
createAutomation(triggers:, actions:) ऐसे arrays लेते हैं जिनके फ़ील्ड्स प्रत्येक entry के type पर निर्भर करते हैं।
boostFacebookPost(interests:) Meta interest ids को strings या numbers के रूप में स्वीकार करता है।

वही मान पास करें जो आप संबंधित REST body में भेजते। JSON argument कोई खामी नहीं है: resolver dispatch से पहले इसे validate करता है, इसलिए अमान्य मान validation error लौटाता है और कोई API call खर्च नहीं करता।

वैकल्पिक arguments और nulls

वैकल्पिक arguments और input objects के अंदर के वैकल्पिक फ़ील्ड्स के लिए, स्पष्ट null को छोड़ दिए जाने के समान माना जाता है। Lists के अंदर के null सदस्य तब सुरक्षित रखे जाते हैं जब list type उनकी अनुमति देता है।

Responses पढ़ना

अधिकांश ऑपरेशन्स एक JSON scalar लौटाते हैं जिसमें पूरा REST response envelope होता है, इसलिए root फ़ील्ड को बिना subfields के चुनें। createPost वर्तमान में एक typed PostResult लौटाता है, इसलिए उसके फ़ील्ड्स चुनें:

mutation {
  createPost(input: {
    post: "Hi"
    platforms: [LINKEDIN]
    idempotencyKey: "linkedin-hi-001"
  }) {
    status
    id
    postIds { platform postUrl }
    errors { platform message code }
  }
}

PostResult जैसे typed response types में raw: JSON! भी शामिल होता है, जिसमें पूरा, अपरिवर्तित REST response होता है:

mutation {
  createPost(input: {
    post: "Hi"
    platforms: [LINKEDIN]
    idempotencyKey: "linkedin-hi-001"
  }) {
    status
    raw
  }
}

raw स्थायी है और इसलिए मौजूद है ताकि REST response में दिखने वाला कोई नया फ़ील्ड GraphQL से कभी अप्राप्य न रहे, जब तक हम उसकी typing पूरी करते हैं। यदि आपको कुछ ऐसा चाहिए जो typed फ़ील्ड्स उपलब्ध नहीं कराते, तो raw माँगें।

मीडिया अपलोड करना

मीडिया bytes GraphQL request के माध्यम से नहीं भेजे जा सकते। GraphQL request 64 KB सीमा के भीतर एक ही JSON document होती है, इसलिए कोई ऐसा फ़ील्ड नहीं है जो फ़ाइल स्वीकार करे, और query के अंदर किसी image को base64 के रूप में encode करना thumbnail से बड़ी किसी भी चीज़ के लिए उस सीमा को पार कर जाएगा। समर्थित तरीका इस समस्या से पूरी तरह बचता है, और किसी भी स्थिति में API के माध्यम से अपलोड करने से तेज़ है, क्योंकि आपके bytes सीधे storage में जाते हैं:

एक upload URL माँगें:

mutation { mediaUploadUrl(contentType: "image/jpeg") }

लौटाए गए JSON से data.mediaUploadUrl.uploadUrl, accessUrl, और contentType पढ़ें।
अपनी फ़ाइल को Ayrshare API पर नहीं, बल्कि सीधे uploadUrl पर PUT करें, और request के Content-Type header को लौटाए गए contentType पर सेट करें।

अपलोड सफल होने के बाद, accessUrl को createPost.input.mediaUrls में पास करें:

mutation {
  createPost(input: {
    post: "With a photo"
    platforms: [INSTAGRAM]
    mediaUrls: ["https://the-returned-access-url"]
    idempotencyKey: "instagram-photo-001"
  }) {
    status
    postIds { platform postUrl }
  }
}

uploadUrl को एक अल्पकालिक write credential मानें और इसे log या उजागर न करें। accessUrl वह media URL है जिसका उपयोग पोस्ट बनाते समय किया जाता है। आप REST upload endpoints का उपयोग जारी रख सकते हैं और परिणामी URLs को GraphQL से संदर्भित कर सकते हैं। दोनों इंटरफ़ेस एक ही media library साझा करते हैं।

आगे पढ़ें

त्रुटियाँ — HTTP status codes, error आकार, और आंशिक सफलता।
सीमाएँ और Billing — query आकार की सीमाएँ और requests की गिनती कैसे होती है।

Get Started

API Endpoints

Multiple Users

Dashboard

Additional

GraphQL API का उपयोग करना

ऑपरेशन ढूँढना

Queries पढ़ती हैं, mutations लिखते हैं

पोस्ट बनाना

Argument types

Enums

JSON scalar

वैकल्पिक arguments और nulls

Responses पढ़ना

मीडिया अपलोड करना

आगे पढ़ें

​ऑपरेशन ढूँढना

​Queries पढ़ती हैं, mutations लिखते हैं

​पोस्ट बनाना

​Argument types

​Enums

​JSON scalar

​वैकल्पिक arguments और nulls

​Responses पढ़ना

​मीडिया अपलोड करना

​आगे पढ़ें

ऑपरेशन ढूँढना

Queries पढ़ती हैं, mutations लिखते हैं

पोस्ट बनाना

Argument types

Enums

JSON scalar

वैकल्पिक arguments और nulls

Responses पढ़ना

मीडिया अपलोड करना

आगे पढ़ें