Developer Docs

API Access دستاویزات

یہ صفحہ production استعمال کے لیے API key flow، سیکیورٹی rules، endpoint catalog، اور testing standards واضح کرتا ہے۔

API access workspace لوڈ ہو رہا ہے...

Live API Tester

اپنی API key کے ساتھ live request چلا کر status، rate-limit headers، اور response payload دیکھیں۔

cURL

curl -X GET "https://sarafa.pk/api/v1/public-rates/gold/cities/karachi" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Client-Platform: server"

Access Rules

API key صرف authenticated user بنا سکتا ہے۔
API key صرف city-wise gold/silver rate endpoints (single-city اور multi-city) کے لیے valid ہے۔
ہر request میں X-API-Key header لازمی ہے۔
Web clients کے لیے allowed website origins شامل کریں اور web platform فعال رکھیں۔
Mobile/server clients کے لیے X-Client-Platform: mobile یا server استعمال کریں۔
Multi-city call کے لیے slugs query param میں comma-separated city slugs دیں (زیادہ سے زیادہ 50).
روزانہ quota ہر key پر enforce ہوتا ہے (exceed ہونے پر 429).
Raw key صرف create کے وقت دکھایا جاتا ہے۔

Endpoint Catalog

Method	Path	Auth	Purpose
POST	/api/v1/auth/v2/login	نہیں	JWT token حاصل کریں
POST	/api/v1/api-keys/	Bearer JWT	API key بنائیں
GET	/api/v1/api-keys/	Bearer JWT	API keys کی فہرست
PATCH	/api/v1/api-keys/{key_id}/access	Bearer JWT	Domain اور platform access اپ ڈیٹ کریں
POST	/api/v1/api-keys/{key_id}/revoke	Bearer JWT	key revoke کریں
GET	/api/v1/api-keys/{key_id}/usage?days=30	Bearer JWT	روزانہ usage رپورٹ
GET	/api/v1/public-rates/gold/cities/{location_slug}	X-API-Key	Single-city سونے کی قیمت
GET	/api/v1/public-rates/gold/cities?slugs={karachi,lahore}	X-API-Key	Multi-city سونے کی قیمتیں
GET	/api/v1/public-rates/silver/cities/{location_slug}	X-API-Key	Single-city چاندی کی قیمت
GET	/api/v1/public-rates/silver/cities?slugs={karachi,lahore}	X-API-Key	Multi-city چاندی کی قیمتیں

Rate Limit Headers

X-RateLimit-Limit-Day - روزانہ quota
X-RateLimit-Remaining-Day - آج باقی requests
X-RateLimit-Reset - Reset timestamp

Platform اور Origin Headers

X-Client-Platform: server | mobile | web
Web requests میں Origin header کو allowed origins کے خلاف validate کیا جاتا ہے۔
Mobile اور server requests میں عموماً Origin نہیں ہوتا، اس لیے X-Client-Platform سیٹ کریں۔

cURL مثالیں

# 1) Login (Get JWT)
curl -X POST "https://sarafa.pk/api/v1/auth/v2/login" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=03001234567&password=YourPassword"

# 2) Create API key
curl -X POST "https://sarafa.pk/api/v1/api-keys/" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Backend Server Key"}'

# 3) Call city gold rate
curl -X GET "https://sarafa.pk/api/v1/public-rates/gold/cities/karachi" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Client-Platform: server"

# 4) Call city silver rate
curl -X GET "https://sarafa.pk/api/v1/public-rates/silver/cities/lahore" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Client-Platform: server"

# 5) Call multi-city gold rates
curl -X GET "https://sarafa.pk/api/v1/public-rates/gold/cities?slugs=karachi,lahore,islamabad" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Client-Platform: mobile"

# 6) Call multi-city silver rates
curl -X GET "https://sarafa.pk/api/v1/public-rates/silver/cities?slugs=karachi,lahore,islamabad" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Client-Platform: mobile"

# 7) Web origin-restricted request
curl -X GET "https://sarafa.pk/api/v1/public-rates/gold/cities/karachi" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Origin: https://app.example.com"

Error Contract

Status	Meaning
401	Missing/invalid auth یا API key
403	Key revoked/disabled/forbidden
404	City یا key resource نہیں ملا
429	روزانہ limit exceed ہو گئی

{ "detail": "message" }

Testing Checklist (Production QA)

JWT login کے بعد API key creation کامیاب ہو۔
Raw key صرف create response میں آئے، list endpoint میں نہیں۔
Web requests پر origin allowlist نافذ ہو۔
Platform restrictions غیر مجاز client types کو بلاک کریں۔
Valid key کے ساتھ gold/silver city endpoints 200 دیں۔
Multi-city endpoints میں requested_count، count، data، not_found درست آئیں۔
Invalid/missing key پر 401 آئے۔
Revoked key پر 403 آئے۔
Daily quota exceed ہونے پر 429 اور reset header آئے۔
Usage endpoint میں آج کے hits اور remaining quota درست ہوں۔
High-concurrency میں limit bypass نہ ہو۔