REST API-lər, HTTP protokolunu istifadə edərək resurslarla (məlumatlarla) işləyir. REST API-nin uğurlu olmasının açarı, düzgün adlandırma qaydaları (naming conventions) və ən yaxşı təcrübələrə (best practices) riayət etməkdir. Bu məqalədə, REST API URI-lərinin necə adlandırılacağına dair praktik tövsiyələr verəcəyik.
1. Resursların Adlandırılması: İsimlərdən İstifadə Edin
URI-lərdə həmişə isimlərdən (nouns) istifadə edin, feillərdən (verbs) deyil. Bu, REST-in “resursa əsaslanan” prinsipinə uyğundur.
Yanlış:
GET /getUsers→ İstifadəçiləri almaq üçün yanlış adlandırma.POST /createUser→ İstifadəçi yaratmaq üçün yanlış adlandırma.DELETE /deleteUser/1→ İstifadəçi silmək üçün yanlış adlandırma.
Doğru:
GET /users→ İstifadəçilərin siyahısını almaq üçün doğru adlandırma.POST /users→ Yeni istifadəçi yaratmaq üçün doğru adlandırma.DELETE /users/1→ ID-si 1 olan istifadəçini silmək üçün doğru adlandırma.
2. Çoxluq Formasından İstifadə Edin
Resurs adları üçün həmişə çoxluq formasından istifadə edin. Bu, API-nin daha oxunaqlı olmasını təmin edir.
Yanlış:
GET /user→ Təklik forması yanlışdır.POST /user→ Təklik forması yanlışdır.
Doğru:
GET /users→ Çoxluq forması doğrudur.POST /users→ Çoxluq forması doğrudur.
3. Kiçik Hərflərdən İstifadə Edin
URI-lərdə həmişə kiçik hərflərdən istifadə edin. Böyük hərflər və ya qarışıq hərflər oxunaqlığı pozur.
Yanlış:
GET /Users→ Böyük hərf yanlışdır.GET /UserDetails→ Böyük hərf yanlışdır.
Doğru:
GET /users→ Kiçik hərflər doğrudur.GET /user-details→ Kiçik hərflər doğrudur.
4. Tire (-) İşarəsindən İstifadə Edin
Söz arası boşluq yerinə tire (-) istifadə edin. Alt xətt (_) oxunaqlığı pozur və bəzi sistemlərdə problem yarada bilər.
Yanlış:
GET /user_details→ Alt xətt yanlışdır.GET /userProfile→ Boşluq yanlışdır.
Doğru:
GET /user-details→ Tire işarəsi doğrudur.GET /user-profile→ Tire işarəsi doğrudur.
5. Fayl Uzantılarından Çəkinin
URI-lərdə fayl uzantıları (.json, .xml) istifadə etməyin. Formatı Content-Type header vasitəsilə müəyyən edin.
Yanlış:
GET /users.json→ Fayl uzantısı yanlışdır.GET /users.xml→ Fayl uzantısı yanlışdır.
Doğru:
GET /users→ Fayl uzantısı olmadan doğrudur. Header:Accept: application/json
6. İyerarxiya Göstərmək Üçün Slash (/) İstifadə Edin
Resurslar arasında iyerarxiya (hierarchiya) göstərmək üçün / istifadə edin.
Məsələn:
GET /users/1/orders→ İstifadəçinin sifarişlərini almaq üçün doğru adlandırma.GET /categories/5/products→ Kateqoriyanın məhsullarını almaq üçün doğru adlandırma.
7. Filtrləmə, Sıralama və Səhifələmə Üçün Sorğu Parametrlərindən İstifadə Edin
Filtrasiya, sıralama və səhifələmə üçün sorğu parametrlərindən (query parameters) istifadə edin.
Məsələn:
GET /users?status=active→ Aktiv istifadəçiləri almaq üçün doğru adlandırma.GET /users?sort=asc&limit=10→ Artan sıra ilə 10 istifadəçi almaq üçün doğru adlandırma.GET /users?page=2&per_page=20→ 2-ci səhifədəki 20 istifadəçi almaq üçün doğru adlandırma.
8. HTTP Metodlarını Əməliyyata Görə Təyin Edin
HTTP metodlarından (GET, POST, PUT, DELETE) istifadə edərək resurs üzərində hansı əməliyyatın aparılacağını təyin edin.
Məsələn:
GET /users→ İstifadəçilərin siyahısını alır.POST /users→ Yeni istifadəçi yaradır.PUT /users/1→ ID-si 1 olan istifadəçini yeniləyir.DELETE /users/1→ ID-si 1 olan istifadəçini silir.
9. Versiyalaşdırma İstifadə Edin
API-nizi versiya ilə təchiz edin. Bu, gələcəkdə API-ni yeniləmək üçün vacibdir.
Məsələn:
GET /v1/users→ Birinci versiya üçün doğru adlandırma.GET /v2/users→ İkinci versiya üçün doğru adlandırma.
10. Dərin İç-içə URI-lərdən Çəkinin
Çox dərin nested (iç-içə) URI-lərdən çəkinin. Ən çox 2–3 səviyyədən artıq nested URI istifadə etməyin.
Yanlış:
GET /users/1/orders/123/items/456→ Çox dərin iç-içə URI yanlışdır.
Doğru:
GET /users/1/orders→ Düzgün səviyyədə iç-içə URI doğrudur.GET /orders/123/items→ Düzgün səviyyədə iç-içə URI doğrudur.
11. HTTP Status Kodlarını Düzgün İstifadə Edin
HTTP status kodlarını düzgün istifadə edin:
- 200 OK: Uğurlu sorğu.
- 201 Created: Yeni resurs yaradıldı.
- 400 Bad Request: Səhv sorğu.
- 401 Unauthorized: İcazə yoxdur.
- 404 Not Found: Resurs tapılmadı.
- 500 Internal Server Error: Server xətası.
12. Ardıcıl Adlandırma Qaydalarına Riayət Edin
Bütün URI-lərdə eyni adlandırma qaydasına riayət edin. Məsələn, hər zaman çoxluq formasından istifadə edin və kiçik hərflərlə yazın.
Nəticə
Düzgün adlandırma qaydalarına riayət etmək REST API-nin oxunaqlığını, istifadəsini və gələcək inkişafını asanlaşdırır. Bu tövsiyələrə əməl etsəniz, daha səmərəli və peşəkar API-lər yarada bilərsiniz.
Uğurlar! 🚀