Veb API-lər və requests kitabxanası

Telefonundakı hava proqnozu, bankın valyuta məzənnələri, xəritədə marşrut — bu məlumatların hamısını proqramlar serverlərdən API (Application Programming Interface) vasitəsilə alır. Educora tətbiqləri də dərsləri saytın API-sindən yükləyir. Veb API sadə razılaşmadır: müəyyən ünvana HTTP sorğusu göndərirsən, server isə adətən JSON cavabı qaytarır. Python-da bunun ən populyar aləti requests kitabxanasıdır.

HTTP qısaca

Sorğu dörd hissədən ibarətdir: metod (nə etmək), URL (hara), başlıqlar (əlavə məlumat: format, açar) və gövdə (göndərilən verilənlər, məsələn, JSON). Cavab status kodu, başlıqlar və gövdədən ibarətdir. URL-dəki ? işarəsindən sonrakı hissə sorğu parametrləridir (query string): ?city=Baku&units=metric.

GET /v1/weather?city=Baku&units=metric HTTP/1.1
Host: api.example.com
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json

{"city": "Baku", "temp": 24.5, "wind": 7.2, "description": "sunny"}

requests ilə sorğular

Kitabxananı kompüterində quraşdır: pip install requests. Brauzerdəki Python şəbəkə sorğuları göndərə bilmir, ona görə bu dərsin kodu işə salınmır — onu öz kompüterində sına. requests.get cavab obyekti qaytarır: status_code, headers, text, json(). Parametrləri URL-ə əl ilə yapışdırma: params lüğəti onları düzgün kodlaşdırır, məsələn, «Sumqayıt» Sumqay%C4%B1t olur.

import requests

url = 'https://api.example.com/v1/weather'
params = {'city': 'Baku', 'units': 'metric'}
headers = {'Accept': 'application/json'}

response = requests.get(url, params=params, headers=headers, timeout=10)
print(response.status_code)
print(response.url)
print(response.headers['Content-Type'])
data = response.json()
print(data['city'], data['temp'])

200
https://api.example.com/v1/weather?city=Baku&units=metric
application/json
Baku 24.5

Yeni obyekt yaratmaq üçün POST göndəririk. json= arqumenti lüğəti JSON-a çevirir və Content-Type: application/json başlığını özü əlavə edir. Uğurlu yaratmada server adətən 201 kodu və yeni obyekti (identifikatoru ilə) qaytarır.

import requests

new_task = {'title': 'Finish the pandas lesson', 'done': False}
r = requests.post('https://api.example.com/v1/tasks', json=new_task, timeout=10)
print(r.status_code)
print(r.json())
print(r.request.headers['Content-Type'])

201
{'id': 42, 'title': 'Finish the pandas lesson', 'done': False}
application/json

Xətalar, vaxt limiti və raise_for_status

Diqqət: 404 və ya 500 cavabı requests üçün xəta deyil — kod sakitcə davam edir. raise_for_status() 4xx və 5xx kodlarında HTTPError qaldırır. Şəbəkə problemləri isə ayrıca istisnalardır: Timeout, ConnectionError; hamısı requests.exceptions.RequestException sinfindən törəyir.

import requests

def get_json(url, **params):
    try:
        r = requests.get(url, params=params, timeout=5)
        r.raise_for_status()
        return r.json()
    except requests.exceptions.Timeout:
        print('The server did not answer in time')
    except requests.exceptions.HTTPError as e:
        print('HTTP error:', e.response.status_code)
    except requests.exceptions.RequestException as e:
        print('Network problem:', type(e).__name__)
    return None

print(get_json('https://api.example.com/v1/weather', city='Atlantis'))

HTTP error: 404
None

API açarlarının təhlükəsizliyi

Əksər API-lər səni açar (API key, token) ilə tanıyır. Açar parol kimidir: onu bilən sənin adından sorğu göndərə, limitini xərcləyə və hətta sənin hesabına pul xərcləyə bilər. Qaydalar:

• Açarı heç vaxt kodun içinə yazma və Git-ə commit etmə — onu mühit dəyişənində saxla.
• .env faylı işlədirsənsə, onu .gitignore-a əlavə et.
• API imkan verirsə, açarı URL-də yox, başlıqda göndər: URL-lər jurnallarda və brauzer tarixçəsində qalır.
• Gizli açarı brauzer və ya mobil tətbiq koduna qoyma — onu istənilən istifadəçi çıxara bilər; belə sorğuları öz serverin vasitəsilə göndər.
• Açar sızıbsa, dərhal onu ləğv et və yenisini yarat.

# Linux / macOS
export WEATHER_API_KEY='paste-your-key-here'

# Windows PowerShell
$env:WEATHER_API_KEY = 'paste-your-key-here'

import os
import requests

api_key = os.environ.get('WEATHER_API_KEY')
if not api_key:
    raise SystemExit('Set the WEATHER_API_KEY environment variable first')

session = requests.Session()
session.headers.update({'Authorization': f'Bearer {api_key}'})
r = session.get('https://api.example.com/v1/weather', params={'city': 'Baku'}, timeout=10)
r.raise_for_status()
print(r.json()['description'])

sunny