طلب GET

نستعرض في هذا المقال إجراء طلبات GET مختلفة والمتطلبات الأساسية لذلك.

طلب GET لعرض صناديق البريد

بفرض لدينا مركز مساعدة على النطاق الفرعي support.example.com سنرسل طلب GET إلى نقطة الاتصال inboxes/ كما يلي:

عنوان URL

https://support.example.com/api/agent/v1/inboxes

معاملات الاستعلام

أمثلة

سنجرب كتابة الطلب GET وإرساله للواجهة البرمجية بعدة طرق:

طلب GET باستخدام Postman

واجهة برنامج Postman سهلة الاستخدام، وتتألف من قسمين أحدهما للطلب والآخر للاستجابة، وتوفر تبويبات واضحة لكتابة معاملات الاستعلام وبيانات التصريح والترويسة وجسم الطلب وغيرها.

توضح الصورة التالية طريقة الحصول على صناديق البريد العائدة لمركز مساعدة والمُنشأة بعد تاريخ 2024/1/1، والتي تندرج تحت الحالة default أو spam مع إظهارها بترتيب تنازلي تبعًا لحروف أسماء صناديق البريد.

معاملات الاستعلام هنا اختيارية لذا استخدامنا بعضها فقط، وحددنا نوع الطلب GET، وكتبنا بجانبه عنوان URL لنقطة الاتصال.

إذا ضغطنا على زر send سنحصل على الاستجابة التالية:

ظهر لنا رمز الخطأ 401 Unauthorized لأننا لغاية الآن لم نكتب مفتاح استيثاق الواجهة البرمجية API_Key، لذا انتقل إلى تبويب التصريح Authorization كما يلي، وأدخل مفتاح API الخاص بك وهو من نوع Bearer:

الآن اضغط على زر Send لإرسال الطلب، ستحصل على استجابة تتضمن المعلومات المطلوبة مع رمز الاستجابة 200 للدلالة على نجاح العملية:

انتبه لصحة كتابة معاملات الاستعلام فأي خطأ املائي مثل تبديل حالة الحروف من صغيرة إلى كبيرة أو غيره يعني أن الواجهة لن تعطيك الاستجابة المطلوبة، في مثالنا إذا بدلنا spam إلى Spam سنحصل على الخطأ 400 Bad Request:

طلب GET باستخدام cURL

تُكتب أوامر cURL وفق الصيغة العامة التالية:

curl [options...] <url>

لا يحتاج الطلب GET لخيار خاص ليفهمه cURL، سنستخدم الخيار header-- لتمرير مفتاح API في ترويسة الطلب والخيار globoff-- لتعطيل ميزة globbing لأن URL الخاص بطلبنا يتضمن أقواس مجال مثل [] أو {}، وبدون تعطيل هذه الميزة سيفهم cURL أننا نستخدم عناوين URL متعددة مكتوبة ضمن أقواس المجال.

لنكتب طلب الحصول على معلومات صناديق البريد العائدة لمركز المساعدة الذي له النطاق الفرعي support.example.com والمُنشأة بعد تاريخ 2024/1/1، وحالتها إما default أو spam مع إظهارها بترتيب تنازلي تبعًا لحروف أسماء الصناديق:

curl --header "Authorization: Bearer 323c566767a73c3e56ab341b08021844dcc7c07e53f31d935dbedc1c6b40e39d" --globoff "https://support.example.com/api/agent/v1/inboxes?after[created_at]=2024-01-01T00%3A00%3A00&statuses[]=default&statuses[]=spam&sort=name.desc" -o response1.json

ينفذ الأمر كما يلي:

وهذا ملف الاستجابة:

انتبه للعبارة has_more في نهاية أسطر الاستجابة، عندما تحمل القيمة false كما في مثالنا فهذا يعني أن جميع النتائج قد ظهرت في الاستجابة، وعندما تحمل القيمة true فهي تُعلمنا أن هناك نتائج إضافية لم تظهر في الاستجابة وهنا يأتي دور معامل ترقيم الصفحات limit إذ يمكنك تمريره ضمن الطلب وإعطائه قيمة مناسبة تكفي لعرض جميع النتائج، ويمكن الاستعانة بقيمة total_count الظاهرة في الاستجابة أيضًا لتعرف إلى مدى ينبغي أن توسع limit.

طلب GET باستخدام لغات البرمجة

سنستعرض صيغة الطلب GET بشروط الاستعلام نفسها بأكثر من لغة برمجة

1. بايثون

تُستخدم المكتبة requests لإرسال طلبات HTTP بلغة بايثون إلى الواجهات البرمجية، وتُكتب طلبات GET بالصيغة التالية:

import requests
url = "https://support.example.com/api/agent/v1/inboxes?after[created_at]=2024-01-01T00:00:00&statuses[]=default&statuses[]=spam&sort=name.desc"
payload = {}
headers = {
  'Authorization': 'Bearer 323c566767a73c3e56ab341b08021844dcc7c07e53f31d935dbedc1c6b40e39d'
  }
response = requests.request("GET", url, headers=headers, data=payload)
print(response.text)

2. Node.js

يمكنك استخدام عدة مكتبات لإرسال طلبات GET بواسطة Node.js نذكر منها Request و Unirest و Native و Axios، اخترنا في مثالنا التالي المكتبة Request:

var request = require('request');
var options = {
  'method': 'GET',
  'url': 'support.example.com/api/agent/v1/inboxes?after[created_at]=2024-01-01T00:00:00&statuses[]=default&statuses[]=spam&sort=name.desc',
  'headers': {
    'Authorization': 'Bearer 323c566767a73c3e56ab341b08021844dcc7c07e53f31d935dbedc1c6b40e39d'
      }
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

3. روبي

تعتمد لغة روبي المكتبة Ruby Net::HTTP للتعامل مع طلبات HTTP المرسلة للواجهات البرمجية، وهذا مثال على صيغة الطلب GET باستخدامها:

var request = require('request');
var options = {
  'method': 'GET',
  'url': 'https://support.example.com/api/agent/v1/inboxes?after[created_at]=2024-01-01T00:00:00&statuses[]=default&statuses[]=spam&sort=name.desc',
  'headers': {
    'Authorization': 'Bearer 323c566767a73c3e56ab341b08021844dcc7c07e53f31d935dbedc1c6b40e39d'
      }
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

4. جافا

توفر جافا مكتبتين لإرسال طلبات HTTP هما Unirest و OkHttp، وقد استخدمنا المكتبة Unirest لكتابة مثالنا التالي:

Unirest.setTimeouts(0, 0);
HttpResponse<String> response = Unirest.get("https://support.example.com/api/agent/v1/inboxes?after[created_at]=2024-01-01T00%3A00%3A00&statuses[]=default&statuses[]=spam&sort=name.desc")
  .header("Authorization", "Bearer 323c566767a73c3e56ab341b08021844dcc7c07e53f31d935dbedc1c6b40e39d")
  .asString();

5. PHP

توفر PHP أدواتٍ عدة للتعامل مع طلبات HTTP المرسلة للواجهات البرمجية، أبرزها المكتبة cURL والمكتبة Guzzle والحزمة HTTP_Request2 والإضافة pecl_http extension، اخترنا هنا المكتبة PHP cURL، ألقِ نظرة على صيغة الطلب GET:

<?php
$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => 'support.example.com/api/agent/v1/inboxes?after[created_at]=2024-01-01T00%3A00%3A00&statuses[]=default&statuses[]=spam&sort=name.desc',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer 323c566767a73c3e56ab341b08021844dcc7c07e53f31d935dbedc1c6b40e39d'
 ),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;