Web API'leri ve requests kütüphanesi

Telefonundaki hava durumu, bir bankanın döviz kurları, haritadaki bir rota: programlar bu verilerin hepsini sunuculardan API (Application Programming Interface) aracılığıyla alır. Educora uygulamaları da dersleri sitenin API'sinden yükler. Bir web API'si basit bir anlaşmadır: belirli bir adrese HTTP isteği gönderirsin, sunucu da genellikle JSON bir yanıt döndürür. Python'da bunun en popüler aracı requests kütüphanesidir.

Kısaca HTTP

Bir istek dört parçadan oluşur: metot (ne yapılacağı), URL (nereye), başlıklar (ek bilgi: biçim, anahtar) ve gövde (gönderilen veri, örneğin JSON). Bir yanıt ise durum kodu, başlıklar ve gövdeden oluşur. URL'deki ? işaretinden sonraki kısım sorgu parametreleridir (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 ile istekler

Kütüphaneyi bilgisayarına kur: pip install requests. Tarayıcıdaki Python ağ istekleri gönderemez; bu yüzden bu dersin kodu burada çalıştırılamaz, onu kendi bilgisayarında dene. requests.get bir yanıt nesnesi döndürür: status_code, headers, text, json(). Parametreleri URL'ye elle yapıştırma: params sözlüğü onları doğru kodlar; örneğin “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 bir nesne oluşturmak için POST göndeririz. json= argümanı sözlüğü JSON'a çevirir ve Content-Type: application/json başlığını kendisi ekler. Başarılı bir oluşturmada sunucu genellikle 201 kodunu ve yeni nesneyi (kimliğiyle birlikte) döndürü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

Hatalar, zaman aşımları ve raise_for_status

Dikkat: 404 ya da 500 yanıtı requests için bir hata değildir; kod sessizce devam eder. raise_for_status(), 4xx ve 5xx kodlarında HTTPError fırlatır. Ağ sorunları ise ayrı istisnalardır: Timeout, ConnectionError; hepsi requests.exceptions.RequestException sınıfından türer.

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 anahtarlarının güvenliği

Çoğu API seni bir anahtarla (API anahtarı, token) tanır. Anahtar bir parola gibidir: onu bilen herkes senin adına istek gönderebilir, limitini tüketebilir, hatta masraf çıkarabilir. Kurallar:

• Anahtarı asla kodun içine yazma ve Git'e commit etme; onu bir ortam değişkeninde sakla.
• Bir .env dosyası kullanıyorsan onu .gitignore dosyasına ekle.
• API izin veriyorsa anahtarı URL'de değil, başlıkta gönder: URL'ler kayıtlarda ve tarayıcı geçmişinde kalır.
• Gizli bir anahtarı tarayıcı ya da mobil uygulama koduna koyma; herhangi bir kullanıcı onu çıkarabilir. Bu tür istekleri kendi sunucun üzerinden gönder.
• Bir anahtar sızdıysa onu hemen iptal et ve yenisini oluştur.

# 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