REST API ishlab chiqish bo'yicha maslahatlar va eng yaxshi amaliyotlar - 1 qism

Kirish va rejalashtirish

Bu REST API-laridagi uchta xabarlarning birinchisidir.

• 1 qism: Kirish va rejalashtirish
• 2-qism: Sxema bo'yicha takliflar, keng tarqalgan xatolar va eskirgan narsalar
• 3-qism: Hujjatlashtirish bo'yicha maslahatlar va asoslardan chetga chiqish

KIRISh

Ushbu kunlarda REST API hamma joyda. Agar siz tarmoq bilan ishlaydigan ilovalarni ishlab chiqayotgan bo'lsangiz, unda kamida bitta kodni iste'mol qilgan bo'lish ehtimoli bor va ehtimol o'zingiz buni o'zingiz yozmoqchi bo'lganingiz uchun o'qiyotgan bo'lsangiz kerak.

Ushbu seriya nima va u nima emas

Ushbu ketma-ket xabarlar RESTga kirish emas. Bu siz REST nima ekanligini va uni amalga oshirishni aniq tushunganingizni anglatadi. Bundan tashqari, bu Web API dizayni va rivojlanishi bo'yicha eng yaxshi amaliyotlar haqida to'liq maqola emas. Internetda allaqachon mavjud bo'lganlar juda ko'p, va imkon qadar ko'proq o'qishni maslahat beraman.

Bu, asosan, REST API-larini ishlab chiqish va amalga oshirishda odamlar tomonidan uchraydigan juda keng tarqalgan va ko'pincha e'tibordan chetda qoladigan xatolar ro'yxati. Bilaman, men ularni boshqa odamlarning API-larida uchratganim uchun emas, balki ulardan ba'zilarini o'zim qilganim uchun. :)

Nima uchun bu yozilgan

Mukammal dunyoda, kimdir REST API-ni ishlab chiqqandan so'ng bajarishi kerak bo'lgan birinchi narsa bu uchun mijoz dasturini yozishdir. Men sizning API-dan foydalanish holati haqida emas, balki odamlar qo'ng'iroq qilishi mumkin bo'lgan so'nggi nuqtalar ro'yxati bilan UI haqida gapirmayapman. O'zingizning yaratilishingizning samarasizligini ochib beradigan hech narsa yo'q, uni o'zingiz to'g'ri ishlatishingiz kerak. Men buni bilaman, chunki men buni o'nlab marta qilishim kerak edi.

Albatta, bizning dunyomiz mukammal emas va aksariyat hollarda dasturni ishlab chiquvchisi API ishlashini tugatgandan so'ng boshqa narsalarga o'tishga majbur bo'ladi, lekin faqat API iste'molchilari uni qaytarib berishga chaqirishi kerak. gunohlar. Men juda ko'p baxtsiz vaziyatda bo'lganman, shuning uchun mening xatolarim va maslahatlarim vaqtni tejashga yordam beradi - yangi xususiyatlarni qo'shish vaqti kelguniga qadar o'zingizning API kodingizga qaytishingizga to'g'ri kelmaydi.

Rejalashtirish

Dan Bickell tomonidan taqdim etilgan rasm

1. Boshlashdan oldin

Siz topishingiz mumkin bo'lgan qancha REST API dizayn va ishlab chiqish hujjatlari va kitoblarini o'rganing! Men bu erda odatiy URI o'rniga otni ishlatib ishlatish kabi oddiy maslahatlar haqida gapirmayman (ha, men shunchaki qildim ...) va hokazo, lekin bu ular haqida boshqa joyda o'qigan deb o'ylayman.

Boshqa variantlarni ko'rib chiqing

REST paradigma sifatida juda mashhur, ammo u ko'plab lazzatlarga ega. Har qanday ishni davom ettirishdan oldin, iloji boricha ko'proq narsani ko'rib chiqishingiz kerak. GrafQL-ni tekshirishni unutmang - bu mutlaqo boshqacha yondashuv bo'lib, u nafaqat ma'lum foydalanish holatlarida ajoyib ko'rinadi, balki Facebook (uni ishlab chiqqan) va GitHub-ning yangi v4 API-da ham qo'llaniladi.

Boshqalar nima qilganiga qarang

Iloji boricha obro'li tashkilotlarning taniqli API-laridan foydalaning va amalda sinab ko'ring. Ishni boshlash uchun bir nechta narsalar: GitHub, Stripe, Twitter, PayPal

2. Jamg'arma

API kichik bo'lib qoladi deb o'ylamang - bu deyarli hech qachon bo'lmaydi. Agar siz uni o'zingizning mijoz ilovangizda ishlatadigan yagona odam bo'lsangiz ham, yaqin orada sizga qo'shimcha nuqta, paginatsiya, tahlil, sinov rejimi kerak bo'ladi va yana nima biladi va bu sizning ilovangiz mashhur bo'lib, boshqa odamlar ish boshlashidan oldin ham kerak bo'ladi. API’ga kirish so‘ralmoqda ...

OK - ehtimol, bu cho'zilib ketgan; ammo odatda dasturiy ta'minotni ishlab chiqishda ro'y berganidek, agar siz erta poydevor qo'ysangiz, uzoq muddatda buning uchun juda to'laysiz. API-lar osonlikcha iste'mol qilinadigan bo'lishi uchun izchil bo'lishi kerakligi sababli, ularga kanal-lenta yordamida xususiyatlarni qo'shishga harakat qilish nafaqat sizni, balki sizning mijozlaringizni ham qiyinlashtiradi.

Bundan tashqari, narsalarni toza saqlash qanchalik yaxshi bo'lsa, ularni tugatish uchun kamroq vaqt ketadi va juda tez orada ...

3. Xususiyat

Kuchli poydevor haqida gapirish; Kod yozishni boshlashdan oldin API uchun spetsifikatsiyani yaratishga harakat qiling. Agar siz buni oldin qilmagan bo'lsangiz, bu zerikarli tuyuladi, lekin u uzoq vaqt davomida to'laydi va ko'p vaqt va qiyinchiliklarni tejaydi.

OpenAPI spetsifikatsiyasi (OAS - ilgari Swagger) hozirgi vaqtda eng mashhur usul bo'lib tuyuladi, chunki tobora ko'proq tashkilotlar va alternativalar unga murojaat qilmoqdalar. Shu bilan bir qatorda, Postman - bu API yaratishning ajoyib muhiti, ammo bu faqat shaxslar yoki kichik ishlab chiquvchilar guruhlari uchun bepul.

Faqatgina siz iste'mol qiladigan kichik ichki API-ni ishlab chiqmasangiz, men ushbu maslahatni e'tiborsiz qoldirmaslikni qat'iy tavsiya qilaman.

4. Tahrirlash

Men ushbu xabarda turli xil tahrirlash usullariga e'tibor qaratmayman, chunki Internetda ushbu mavzu bo'yicha ko'plab maxsus manbalar mavjud. Men qat'iy versiyani tanlab, unga amal qilish qanchalik muhimligini ta'kidlashga harakat qilaman. Bundan tashqari, yillar davomida menga yaxshi xizmat qilgan yondashuvni taqdim etaman.

Nima uchun bu muhim

Versiyalarni ishlab chiqishga kuchli yondashish iste'molchilaringizni (va shuning uchun sizning oxirgi foydalanuvchilaringizni) xotirjamlik bilan ta'minlaydi, chunki bu API o'zgarishlarini mavjud mijoz ilovalarining ishlashiga xalaqit bermaydi. Mijoz dasturlarining o'zi bir xil ishlab chiquvchi yoki API bilan bir xil tashkilot tomonidan ishlab chiqilgan bo'lsa ham, API yangilanishi mavjud bo'lganda eskirgan mijozlardan foydalanish mumkin.

Ushbu hodisaning juda tez-tez uchraydigan holati - mobil yoki ish stoli operatsion tizimidagi mijoz dasturlari, bu erda ishlab chiquvchilar kamdan-kam yangilanish tsiklini to'liq nazorat qilishadi. Mijozlarni yangilash mexanizmlari qanchalik yaxshi va avtomatlashtirilgan bo'lishidan qat'i nazar, deyarli har doim foydalanuvchilar sizning mijoz ilovalaringizning so'nggi versiyasini ishlatayotganiga 100% amin bo'lolmaysiz.

Sukut bo'yicha yoqilgan ilovalar uchun iOS-da juda ishonchli avtomatik yangilanish mexanizmi mavjud, ammo foydalanuvchining xohishiga va tarmoq holatiga qarab, ularning qurilmasi keyingi safar ishga tushganda mijoz ilovasini yangilash imkoniyatiga ega bo'lmasligi mumkin. Xuddi shu narsa Android-ning yangi versiyalari uchun ham amal qiladi, eski versiyalari esa ilova yangilanishlarida ancha orqada qolishi mumkin.

Boshqa tomondan, ish stoli ilovalari avtomatik yangilanish mexanizmini ta'minlay olmasligi yoki ta'minlamasligi mumkin - ammo bu ko'p vaqt qo'shilgan va har doim (masalan, korxona sharoitida) tezkor yangilashga imkon bermaydigan holatlar mavjud. Hatto brauzer mijozi ilovalari (va ko'p holatlarda) ularning orqa qismidan ajratib olinishi mumkin va shuning uchun API-ga nisbatan butunlay boshqacha tsiklga ega bo'lishi mumkin.

O'zingizning iste'molchilaringiz bilan bo'lgan o'zgarishlar haqida xabar bering

Agar sizda eng yaxshi versiya tizimiga ega mukammal API mavjud bo'lsa ham, bu sizning iste'molchilaringiz uning to'liq imkoniyatlaridan xabardor bo'lmasa, hech narsa degani emas. O'zgarishlar va yangi xususiyatlar bilan bog'lanish sizning foydalanuvchilaringiz ulardan to'liq foyda olishlari uchun juda muhimdir. Bundan ham muhimi, foydalanuvchilaringizni eskirishi yoki olib tashlanishi kerak bo'lgan jihatlar to'g'risida oldindan ogohlantirishdir, shuning uchun ular mijozlarining yangi versiyalarini yangilash, sinab ko'rish va jo'natish uchun etarli vaqtga egalar.

Yangilangan hujjatlarni saqlash va har bir versiya uchun batafsil o'zgarishlarni nashr qilish juda muhim va sizning rivojlanish tsiklingizning bir qismi bo'lishi kerak.

Katta / kichik versiyaga yondashuv

Bir necha yillardan beri tahrirlashning yondashuvi - bu katta / kichik versiyalar sxemasi. Sizning API asosiy versiya raqami bilan tavsiflanadi, agar u (agar siz to'g'ri ish qilsangiz) yangilanish mavjud bo'lganda yangilanadi va istalgan vaqtda yangilanib turadigan kichik versiya raqami bor.

Boshqa tomondan qaralganda, har bir asosiy versiya, shu vaqtning o'zida qancha kichik versiyalar chiqsa ham, API manbalari va sxemasi uning hayot aylanishi davomida buzilmasligini kafolatlaydi. Kichik versiyalari orqaga qarab mos keladi.

Katta versiya uchun API asosiy URL qismi (masalan, https://api.myserver.com/v1/endpoint) va kichik versiyani so'rov sarlavhasi orqali tanlab olish odatiy holdir. Talab sarlavhasi berilmagan bo'lsa, eng so'nggi kichik versiyadan foydalaniladi. Ushbu yondashuvga amal qiladigan ko'plab ommabop API-lar mavjud, ularning eng sevimlisi Stripe (kichik versiyalar uchun chiqarilgan sanadan foydalanadi).

Keyingi bo'limlarda sizning API-ning yangilanishlari haqida gapirganda, men ushbu yondashuv haqida yana bir bor eslatib o'taman, ammo sizning talablaringizga mos keladigan o'zingizning rasmiy versiyalash tizimini tanlashingiz kerak. Shuni yodda tutingki, siz bir marta qilganingizda, unga sodiq qolishingiz kerak.

5. Sinov

Bu siz ishlab chiqarmaganingizda juda yaxshi

Umuman olganda, dasturiy ta'minotni ishlab chiqish jarayonining ajralmas qismi sifatida, sinov API uchun juda muhimdir. API odatda haqiqat manbai bo'lgan server va bir yoki bir nechta mijoz ilovalari o'rtasidagi bog'liqlik vazifasini o'taganligi sababli, ular har qanday holatda ishonchli bo'lishi kerak va hech qanday tarzda buzilgan ishlab chiqarishga kirishga qodir emas. Bundan tashqari, ular odatda Internetga duch kelishadi va shuning uchun ko'plab xavf-xatarlarga duchor bo'lishlari sababli, ular keng tarqalgan va odatiy bo'lmagan stsenariylarning sinchkovlik bilan tekshirilishi kerak.

Swagger, Postman yoki REST konsollari kabi vositalar orqali so'nggi nuqtalaringizga qo'ng'iroq qilib qo'lda tekshirish, siz faqatgina rivojlanishning turli xil xususiyatlarini sinab ko'rayotganingizda chaqaloq rivojlanishining dastlabki bosqichlarida sizga yordam berishi mumkin. Avtomatlashtirilgan testlar to'plamini erta turishdan boshlab tayyor mahsulot sifati bilan farq qiladi.

O'z tabiatiga ko'ra, API funktsional test uchun ideal nomzoddir. Qurilmaning ichki dasturiy ta'minotini sinab ko'rish juda muhimdir (boshqa har qanday dastur uchun bo'lgani kabi), ammo, mening fikrimcha, API ni funktsional sinovdan o'tkazish va uni qora qutiga solishtirish sizga sarflagan vaqtingiz uchun ko'proq ahamiyatga ega bo'ladi.

Sinov paytida siz sozlashingiz va yirtib tashlashingiz mumkin bo'lgan sinov ma'lumotlar bazasini saqlash bu jarayonning ajralmas qismidir. Oldingi muammolarga (ishlab chiqarishda kuzatilgan yoki iste'molchilar tomonidan bildirilgan) qo'shilgan ma'lumotlarga qo'shishni davom eting va ushbu xatolarni butunlay va to'liq yo'q qilishingizga ishonch hosil qilish uchun test to'plamingizni regressiya testlari bilan boyitib boring.

Hatto eng g'alati holatlarni ham sinab ko'rmaguningizcha, kirish parametrlarini tasdiqlash tugallandi, deb o'ylamang (mijoz dasturlari juda xato bo'lishi mumkinligini unutmang). Nihoyat, qolgan bir nechta ishlamay qolgan xatolarni ko'rish, iste'molchilarning xulq-atvorini kuzatish va testdan o'tkazish stsenariylarini yaratish uchun ushbu ma'lumotlardan foydalanish uchun vaqtni to'g'ri ro'yxatga olish infratuzilmasiga vaqt ajrating.

6. Joylashtirish

Siz allaqachon payqagandirsiz (yoki o'qishda davom etayotganingizda sezasiz), ushbu post narsalarni buzmaydigan API yaratish uchun ko'proq e'tibor qaratadi. Deyarli barcha dasturiy mahsulotlardagi narsalarni buzadigan eng dahshatli bosqich, albatta, tarqatishdir.

Aksariyat hollarda, agar siz sinov va versiyani to'g'ri bajargan bo'lsangiz, tarqatish paytida muammoga duch kelish ehtimoli juda kam; ammo, bu erda qo'shimcha yordam bo'lishi mumkin bo'lgan bir nechta maslahatlar mavjud.

Hamma narsani dekou qiling

Bu juda keng tarqalgan stsenariy:

Sizning API tashqi tashkilotlar tomonidan ishlab chiqilgan ikkita B2B mijozlariga ma'lumotlarni taqdim etadi, bir nechta mobil ilovalar va o'z tashkilotingiz tomonidan ishlab chiqilgan veb-ilovaga xizmat qiladi va server dasturining ajralmas qismi bo'lib, unga veb orqali kirish mumkin bo'ladi. , ma'muriy maqsadlar uchun.

Bu murakkab tuyulishi mumkin, ammo men avvallari sodda yoki murakkabroq o'zgarishlarni ko'p marotaba ko'rganman. Bu erda muhim jihat shundaki, API, tashkilotning asosi bo'lishiga qaramay, kamida boshqa vazifalarga ega bo'lgan kamida bitta server ilovasi bilan mahkam bog'langan.

Bu shuni anglatadiki, server ilovasini yangilash vaqti kelganda, agar biron bir narsa buzilsa, API ham buziladi. Agar bu ro'y bersa, API o'zi bilan birga barcha iste'molchilarni yo'q qiladi va oxir oqibat foydalanuvchilarning g'azabi kompaniyaga tushadi.

Sizning foydalanuvchilaringizga noqulaylik - bu siz istagan so'nggi narsa

Ushbu kontekstda mahkam bog'lanishning yana bir kamchiligi shundaki, bitta ilovani chiqarish tsikli qolganlarga ta'sir qiladi. Buning uchun kompleks rejalashtirish va joylashishni sozlashni talab qiladi. Bundan tashqari, bu biznes nuqtai nazaridan hech qanday ma'noga ega emas (har bir ilova o'z vaqtida, qolganlariga ta'sir qilmasdan chiqarilishi kerak).

Agar sizning API va boshqa ilovalaringiz infratuzilmaning mustaqil modullari sifatida ishlab chiqilgan bo'lsa, unda bularning barchasi o'chib ketadi. Kimdir ko'proq alohida modulga ega bo'lish ko'proq ishlamay qolish degan ma'noni anglatadi, ammo bu to'g'ri versiya va sinov yordamida hal qilinishi mumkin. Bundan tashqari, sizning API-ning yangi versiyasi joylashishni buzgan taqdirda ham, sizning jamoangiz buni birinchi bo'lib bilib oladi. Bu holda, agar bundan yaxshi narsa qilinmasa, siz hamma narsa to'g'ri ishlayotganiga amin bo'lguningizcha mijozlaringizni relizlarini ikki kunga kechiktirishingiz mumkin.

Qattiq sinovdan ehtiyot bo'lishingiz kerak bo'lgan xavfli holatlar bu sizning server ilovangizning yangi versiyasi sizning API mavjud versiyangizni buzganda. Shunga qaramay, buning oldini olishning yagona usuli - to'g'ri ishlab chiqish va sinovdan o'tkazgan holda qat'iy ishlab chiqish jarayoni. O'zingizning infratuzilmangizning barcha qismlarini o'ziga xos modul sifatida muomala qilish ushbu yondashuvni yanada kuchaytiradi.

7. (Shafqatli) Eskirish

Ba'zi bir vaqtlarda, sizning ilovangiz pishib etgunga qadar, hozirgi API-ning asosiy versiyasini yangisiga almashtirish kerak bo'ladi. Ishlab chiqilayotgan mijoz ilovalari ham yangi versiyasiga yangilanishi kerak, ammo bu vaqt talab qilishi mumkin.

Bundan tashqari, ishlab chiqaruvchilar tomonidan darhol amalga oshirilgan harakatlar mijoz ilovalari uchun darhol yangilanishni anglatmaydi. Veb-ilovalarning yangilangan versiyalari chiqqandan so'ng oxirgi foydalanuvchilarga taqdim etilishi mumkin bo'lsa-da, mobil va mahalliy OS-ning eski versiyalari uzoq vaqt davomida qolishga moyildir. Ba'zi bir foydalanuvchilar o'zlarining telefonlari yoki kompyuterlaridagi ilovalarni yangilash jarayonini haqiqatdan ham tushunmaydilar (yoki hatto xabardor ham emas). Agar o'sha ilovalar to'satdan ishlamay qolsa, foydalanuvchilar shunchaki ularni ishlatishni to'xtatishi mumkin.

Katta API versiyasining eskirishi xizmatni to'xtatishni anglatmaydi. Eskirgan versiya aniq vaqt davomida (iloji boricha) iste'molchilarga aniq va qayta-qayta etkaziladigan (oxirigacha yaqin) xabarlar bilan ishlashni davom ettirishi kerak. Ideal holda, sizning API-ning eski versiyalari hech qachon ishlashni to'xtatmasligi kerak, agar ular xavfsizlikka xavf tug'dirmasa yoki sizning kompyuteringizga zarar etkazmasa.

8. Ko'pincha e'tiborga olinmaydigan yaxshi amaliyotlar

Resurslar uchun ko'p yoki yakka shakllardan foydalanishingiz mumkin, ammo ikkalasini ham emas

/ avtomobillar yaxshi, va / mashina ham yaxshi, lekin siz ikkalasini ham ishlata olmaysiz. Bitta shaklni tanlang va unga butun API bo'ylab yopishtiring. Agar shunday qilmasangiz, kelajakda iste'molchilaringizni va ehtimol o'zingizning ishlab chiquvchilaringizni yoki o'zingizni chalkashtirib yuborasiz.

PUT va PATCH javoblarida yangilangan ob'ektlarni qaytaring

PUT yoki PATCH fe'llari orqali muvaffaqiyatli so'rovdan so'ng, mijoz odatda yangilangan manbaning holatini bilishi kerak. Bir vaqtning o'zida bir nechta mijozlar uni yangilab turishlari mumkinligi sababli, yangilash amalga oshirilayotgan vaqtda resurs holati to'g'risida har kimni xabardor qilishning yagona usuli.

Cookie fayllari va PHPSESSIONID

Bu PHP tomonidan ishlab chiqilgan dasturlarda juda keng tarqalgan. API o'zining shaxsiy autentifikatsiya tokenidan foydalanadi, ammo bilmagan holda, PHP-ning odatiy seanslarini qayta ishlata oladigan dasturchiga hamma javoblar, shuningdek, qo'rqib ketgan PHPSESSIONID cookie-fayllarini ham o'z ichiga oladi! Bu uzoq vaqt davomida har xil xatolarga olib keladi, chunki hech kim cookie haqida xabardor qilinmaydi, chunki hech kim uni bu erda joylashtirgan deb o'ylamaydi.

Cookie-fayllar, umuman olganda, REST tomonidan aniq taqiqlanmagan. Noto'g'ri ishlatilgan bo'lsa, ular muammoga olib kelishi mumkin (masalan, agar siz o'zingizning API mexanizmi orqali avtorizatsiya qilinishi kerak bo'lgan alohida domenga kirishga harakat qilsangiz), ammo ular biron bir spetsifikatsiya bilan taqiqlanmagan. Nimadan qochish kerak, lekin bir vaqtning o'zida autentifikatsiya qilishning bir nechta shakllaridan foydalanilmoqda.

PHP-ning seanslarini qayta ishlashga kelsak, siz hech qachon o'zingizning API autentifikatsiya tokeningiz sifatida PHPSESSIONID cookie-sini ishlatishni xohlamasangiz (hech qanday maslahat bermayman!), Siz hech qachon API uchun odatiy PHP cookie-uslubiga ishonmasligingiz kerak. Mening maslahatim sizning afzal autentifikatsiya usulingizni amalga oshiradigan maxsus sessiya bilan ishlash mexanizmini amalga oshirishdir.

Ichki xatolarni yoki amalga oshirish tafsilotlarini fosh qilmang

Yillar davomida men buni son-sanoqsiz holatlarda, hatto yirik kompaniyalarning mashhur API-larida ko'rdim. Javoblaringizda ichki (masalan, SQL) xatolarni fosh qilish juda yaxshi emas! Kelgusida ma'lumot olish uchun ularni ro'yxatga olishning ishonchli usulini toping, ammo ularni API javoblarida umumiy 500 - Ichki server xatosi deb tarjima qiling.

Majburiy xkcd - har doim tegishli.

Bu rivojlanish jarayonida erta qilishingiz kerak bo'lgan birinchi narsalardan biridir. Xavfsizlik Internetda fosh qilinadigan xizmat uchun eng muhim tashvish bo'lishi kerak.

Bu REST API-laridagi uchta postlardagi birinchi bo'ldi.

Keyingisini mana bu erda o'qishingiz mumkin:
2-qism: Sxema bo'yicha takliflar, keng tarqalgan xatolar va eskirishi