طلب GET

نوضح في هذا المقال ما هي طلبات GET، وكيفية إرسال هذه الطلبات لواجهة زيتون البرمجية من خلال عدة أمثلة عملية متنوعة بمختلف لغات البرمجة.

ما هو طلب GET

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

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

إذا كان لدينا مركز مساعدة على النطاق example.com، وأردنا عرض كافة صناديق البريد في هذا المركز التي لها الحالة active أو deleted، مع إظهارها بترتيب تنازلي تبعًا لحروف أسماء صناديق البريد، سنرسل طلب GET لنقطة الوصول List all inboxes، ويمكن إرسال هذا الطلب بعدة طرق:

باستخدام cURL

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

curl [options...] <url>

نمرر في القسم options عدة خيارات مثل:

• header-- أو H- لتمرير معلومات إضافية في ترويسة الطلب، كمفتاح الواجهة، أو نوع المحتوى
• output-- أو o- لحفظ الاستجابة في ملف بدل عرضها على الشاشة
• globoff-- لتعطيل ميزة globbing في حال تضمن عنوان الطلب أقواس مثل [] أو {}

لنكتب طلب cURL لعرض بيانات صناديق البريد مع تصفية النتائج لتشمل الصناديق الواردة الفعالة التي لها الحالة active والمحذوفة التي لها الحالة deleted:

curl "https://example.com/api/agent/v1/inboxes?domain=example.com&statuses[]=active&statuses[]=deleted&sort=name.desc" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     --globoff

ننتبه لصحة كتابة معاملات الاستعلام، فأي خطأ إملائي كتبديل قيمة المعامل active إلى Active يعني أن الواجهة لن تعطينا الاستجابة المطلوبة.

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

سنستعرض صيغة الطلب GET لإجراء الاستعلام السابق لعرض صناديق البريد بأكثر من لغة برمجة

1. بايثون

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

import requests
url = "https://example.com/api/agent/v1/inboxes?statuses[]=default&statuses[]=spam&sort=name.desc"
payload = {}
headers = {
'Authorization': 'Bearer YOUR_API_KEY'
}
response = requests.request("GET", url, headers=headers, data=payload)
print(response.text)

Node.js .2

يمكن استخدام عدة مكتبات لإرسال طلبات GET بواسطة Node.js مثل request و unirest و native و axios، اخترنا في المثال التالي المكتبة request:

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

3. روبي

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

var request = require('request');
var options = {
  method: 'GET',
  url: 'https://example.com/api/agent/v1/inboxes?statuses[]=default&statuses[]=spam&sort=name.desc',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
};
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://example.com/api/agent/v1/inboxes?statuses[]=default&statuses[]=spam&sort=name.desc")
    .header("Authorization", "Bearer YOUR_API_KEY")
    .asString();

PHP .5

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

<?php
$curl = curl_init();
curl_setopt_array($curl, array(
    CURLOPT_URL => 'https://example.com/api/agent/v1/inboxes?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 YOUR_API_KEY'
    ),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;