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! 🚀