REST API для пачатківцяў: рэсурсы, методы, коды статусу і абсэнція стану

„Выучыце REST API“ — гэта парадакт, які чуе кожны новы разработчык, але рэдкасцю супакоўваецца чытальнай адпаведнасцю гэтых слоў. Большасць адпаведнасцей або занурвае чытальніка ў вокабуляр (дзеясловы, канцэнтры, станоўнасць), або спраўляе іх да „таго, што з’яеднае фронтэнд і бэкэнд“, што ўсё правда, але не даўае нічы якіснага.

У гэтым кяле вядомы мяжовы падход. Вы выучыце пяць ідэй, з якіх складаецца практычна кожны REST API, ментальную модель, якая дапамагае іх запам’ятаваць, таму, дзе REST выкорыстоўваецца ў практычнай інжынерскай работе, а таксама практычную последоваснасць для стварэння і тэставання вашага першага API з адпаведнымі інструментамі, а таксама пашкоды, якія часта спамоцавляють пачатківцаў.

Короткая адпаведнасць

REST API — это набор правіл, які дазваляюць двум прыграмам кантактаўвацца через Інтернет. Найчастае гэта фронтэнд, які запрашвае бэкэнд пра даны або прасіць яго ўтримваць якісь матэрыял. Гэта панявленне здаецца абстрактным, пакуль вы не створыце такі API, адкуль яно часта быстра становіцца зрозумелым. Самэ гэтая прычына заставляе REST часта быць аднам з першых справжняях концэпцый бэкэнда, якія вучаць люди, незалежна ад таго, чы рашаць вони спеціялізавацца на роботе з серверамі чы стаць развівачамі «полныя стэк», якіе керуюць обомі часткамі прыграмы.

REST — абвяртанне Representational State Transfer, архітэктурны стыль, які быў сформалізаваны для апісаў, як сам Інтернет павінен працаваць. Для эфектывага викорыстоўвання яго не трэба формальнай тэорыі; саме практычныя правіла, прыведзены нижэй, є фундаментам для рэальных REST API.

Чаму REST так заплутвае багато пачатківцав

Два фактара робяць гэты тэму складней, чым яна магла б быць.

Першым ўскладненням являецца змена значэння слоўніка. У інтэрнете термін „API“ выкорыстоўваецца практычна для будзь-якага інтерфейсу, які адна програма надае іншай: API прыгледача, функціі бібліятэкі, хмарныя сервісы. REST — это адна з конкрэтных і дужа популярных методак разрабаткі веб-API. У зв’язку з такой шырокай падазранасцю люди часта вжываюць термін „API“, маючы на увазе „REST API“, і тады тыя, хто вучыцца, не можуць чытка адзначыць, дзе заканчваецца одна концэпцыя і почынайцца іншая.

Другім ускладненням є тое, што API не мае візуальнага аспекту. Кнопка чы ўпорядкуванне — гэта тое, што можна побачыць; REST API такога не мае. Цэлкам можліва працавацы над проектамі фронтэнду працоўнае часы, вважаючы „закрыць запыт да API“ чымось незрозумелым. Плутанне зазвычай выявляецца тады, калі нарэшце патрабуецца стварыць власны API, і концэпцыя павінна стаць конкрэтной адразу.

Пяць ідэй, якія лежачы за кожным REST API

Якщо не вжываць акронімы, REST API — это узгоджаны спосаб прасылкі та аброхавання дадзейчына праз HTTP за дапамою URL-адрэсаў і невялікага комплексу стандартных дзеянняў. Пяць ідэй пакрываюць практычна все.

Рэсурсы і ўсеіх их URL-адрэсы

Рэсурс — это тое, чым керуе API: корыстнікі, пасты, замовленні, задачы. Кожны рэсурс або група рэсурсаў мае свой сабскі адрес. /users зазвычай аднасаецца да групы корыстнікаў, тады як /orders/42 — да аднаго конкрэтнага замовлення. Хорашыя прыклады дизайна REST называюць рэсурсы іменамі і дазволяюць методу HTTP описваць дзеянне, таму мы бачымо /orders/42, а не /getOrder?id=42.

Методы HTTP

Метада паведамляе серверу, што вы хочаце зробіць з рэсурсам:

• GET чытае дадзейчыну без яе змены.

POST ствараець ўсё новае, зазвычай унутрь калекцыі, такой як /tasks.

PUT заменяе існуючы ресурс, тады як PATCH апдэюе частку ўсіх його даных.

DELETE выкарыстоўваецца для ўдалення ресурса.

Адна з важлівых характэрыстыкаў, якую варта выучыць з самага пачатку, — це ідэмпотентнасць. Аперацыі GET, PUT і DELETE павінны быць ідэмпотентнымі: двачорговая адправка таго ж запиту заставляе сервер у тым самым стане, як і пасля аднарочнай адправкі. POST зазвычай не ёсць ідэмпотентным, адтуды два ідэнтычных запиту можу стварыць два записы. Гэта разліканне падказвае багато рашэнняў па дизайну API, напрыклад, чаму перапыткі є безпечнымі для дзеякіх запытоў, а рызыковымі для іншых.

Запыты і адпаведзі

Кліент адресуе запит даўнему з тых URL-адрэс. У запытанні ўключаюцца метод, URL, заголовкі (метаданы, такія як тип кантэнту або токен автарызаціі), а таксама, для методаў уродзе POST чы PATCH, тэла запытання. Сервер адпавядае рэспонсам, у якім ўключаюцца код статусу, заголовкі і зазвычай тэла рэспонсу. У сучасных API тэла рэспонсу практычна завжды ў формате JSON.

Коды статусу

Кожна адказ прыносіць трывязначны номер, які падсумавляе рэзультат. Для успеху вы пабудзеце бачыць 200, калі рэсурс не існуе — 404, а калі на серверы ўзнікла проблема — 500. Першы цифра паведамляе пра категорію: 2xx означае успех, 4xx — кліент апрацаваў інфармацыю, якую сервер не можа прыняць (некоректны запит, відсутная аутантыкацыя, невядомы рэсурс), а 5xx — сам сервер меў проблему. Адразу ж аналізаваць категорію — гэта найшырэйшы спосаб з’ясавіць, яку частку системы трэба дакладней расследаваць.

Безстановасць

Кожны кансэкт должен мець усё, што патрэбна серверу, каб яго обработаць. Сервер не павяржыцца на тое, што вы прасілі чыраўгэў. Напрыклад, якщо канцэнтпункт выкалічвае аутентыкацыю пользователя, кожны кансэкт мець трэбаваныя дакументы, часта токен у загалоўку. Безстановасць — гэта тое, што робіць REST API простымі для масштабавання: кожны экземпляр сервера можа обрабоцваць будзь-яны кансэкт, таму што ніхто з іх не павяржыцца на прыватную память размовы.

Калі гэтыя пяць ідэй стануць зрозумелымі, большасць дакументацыі REST API перестане выглядаць як мова іншай краіны. Практычна кожная сторонка-даведнік, яку вы зустрэце, — цэла проста спіс рысакоў, методаў, якія яны падтрымляюць, формы тэла кансэкта і адпаведзі і кодаў статусу, якія можна атрымаць.

Ментальны модэль: замовленне ў рестаране

Рэстаран — годны аналагія. Кліянты не заходзяць у кухню і не гатуюць ўжынку. Яны чытаюць меню, паведамляюць офіцыянту, што хочуць, а кухня гатоўвае і прыносіць ужынак.

• Меню — это дасягліванне API: у яму пераказана, што можна запрашваць.
• Офіцыянт — это цыкл запита і адпаведзі, який праносіць ваш замовленне і вяртае рэзультат.
• Кухня — это сервер, який выканае роботу, яку вы ніколі не бачыце безпосередна.

Якща апляіраваць гэтых методаў да практычных ситуацый, GET выконвае запит пра тое, што ёсць у меню, або пераканальваецца, што ўжо ёсць на вашым столе. POST выконвае новы замовленне. DELETE вяртае страву назад. Вам не трэба знать, як унутршна арганізавана кухня; вам проста трэба правільна здаць замовленне, і вы зможаце рачыцацца прыемным, аднаковым адказам ў кожны раз. Гэтая аналагія мае сваія меры (рэстараны памятаюць ваш стол, тады як безстацыйны API — ні), але ёна добра паказвае разпад адпаведальнасцяў.

Дзе REST выкорыстоўваецца ў рэальнай інжынернай праце

REST — гэта не толькі кніжны экзаперымент. Ён ўключаецца ў ўседзёныя задачі практычна кожнай команды, якая працуе над продуктам:

• Разработчык фронтэнду вызывае канцэнтры REST, каб заваносіць прафіль, адправляць форму чыста апавяржваць панель керування.

Разработчык бэкенду проектуе і падтрымлівае гэтыя канцэнтры, адначынаючы, якія даныя будуць вярнутыя і у якой форме.

Разработчык фул-стака выкаанае і тое, і другое: інодзе проектуе канцэнтр, а потым за той жа час выкарыстоўвае яго з інтэрфейсу корыстніка.

Мобільныя прыкладненні, інтеграцыі з трэцімі сторонамі та партнерскія компаніі часта взаімаюцца з продуктам абсалютна через яго REST API, без жаднага інтэрфейсу корыстніка.

Гэты апошні момант ў значныяй меры ўзначыў, чаму REST стаў стандартным стылем для веб-API. Адзін рэтельна спроектаваны набор канцэнтраў можа адразу падтрымваць кліент у браузеры, дапыткі для iOS і Android, а таксама інтэграцыю з зовнішнімі партнерамі. Рэтельны дизайн гэтых канцэнтраў мае важнае значэнне, адтолькі кожны кліент у паўнай меры залежыць ад яных; наша стаття па прычынам кантракта API, якія пагрожуюць надзеям фронтэнду розглядае проблемы, якія выступаюць, калі гэта не робится.

Чаму REST застаецца правым пачатковым пунктом

Існуюць іншыя падходы. GraphQL і gRPC, сярод іншых, рашаюць певныя проблемы болей элегантна, чым REST — напрыклад, дазваляючы кліентам запрашваць толькі тыя поля, якія ў іх патрэбны, або забезпечваючы калякі межу служб. REST застаецца найлепшым варыянтам для пачатківаўцаў з трох практычных прычын.

Паўначальна прычына — гэта тое, што REST ёсць практычна скуды. Большасць публічных API, якія вы, верагацей, будете викорыстоўваць — ад прадаўцоў аплатаў да дадзеных па пагодным умовам і соцыяльных платформ — адказваюць за дапамогу інтэрфейса REST, часта як стандартна апштата. Як толькі вы ўвучыцеся ў яго, у вас з’яўляецца ментальная модель, якую можна воспаліваць ў кожны раз, калі трэба чытаць незнайомую дакументацыю.

Другая прычына — гэта адпаведнасць REST да сэрцаўай структуры веба. Методы HTTP і коды статусу не былі створаны спецыяльна для REST; гэта протаколы, якія вже викорыстоўваюць браузеры і серверы. Правільнае вучэнне REST означае розумеў, як функцыонуе веб пад любым фрэймворкам, які вы викорыстоўваеце, і гэтыя знання застаюцца актуальнымі незалежна ад конкрэтных бібліятак.

Трэцім, гэта ўласна наступны крок пасля аснов фронтэнд-разработкі. Калі вы вже адчуваеце сябе впевнена ў HTML, CSS і JavaScript, момент, калі ваш інтерфейс пачынае завантажваць рэальныя даны заместо жорстка заданых месца падставлень, зазвычай ёсць тады, калі проект пераходзіць з стадіі протатыпа ў ўтварэння чагось, што люди можаць фактычна выкарыстоўваць. Для багаціх разработчыкаў, якія прывязаны да фронтэнду, самэ гэта ёсць момент, калі стварэнне власнага API перестае быць неабавязковым, і пачынаецца шлях да роботы з цэлым стаком. Калі пазней захочаце дэтальна пораўняць стылі, адзірніце REST проты GraphQL і аспекты, якія вплываюць на выбор кожнага.

Стварэнне вашага першага REST API з Node.js і Express

Чытанне толькі дае певныя адказы на гэтыя запитанні. Всё стае ясна, калі вы створылі ўжо што-небудзь, нават мінімальную працоўную версію. Тыповы першы проект на Node.js і Express выглядае так:

1. Створыце мінімальны сервер, які прыймае запиты HTTP на певным порту.
2. Дадзіце маршрут, напрыклад /tasks, і прыяўязаце яго да обробніка запитоў GET, які вяртае спіс.
3. Дадзіце обробнік запитоў POST на тым жа маршруце, які прыймае новыя задачы; на гэтым этапе дастатнька ўтримваць іх у простым масіве ў памяці.
4. Дадзіце обробнікі запитоў PUT (або PATCH) і DELETE, зазвычай на маршруце /tasks/:id, для адчынення і выдалення адзінаковых елементаў.
5. Калі структура API будзе адпавядаць вашым патрабаванням, заменіце масів на справжню базу дадзенаў.
6. Перапрацаваце кожны маршрут за допамогай такога інструмента, як Postman, прычым перш чым працаваць з фронтэндам.

Два аспекты дапамагаюць гэтам практыку працаваць эфективна. Зачынэнне з масіву ў памяці дапамага сфармаваць увагу на маршрутах, методах і кодах статусу, а не на налажоўкі базы дадзеных. А пасляпэльны крок — тэставанне маршрутаў адособлена — являецца тым, чаго пачатківцы часта праскакваюць. Перакананне ў правільнасці API сама по сабе, прычым не пакладаючыся на інтэрфейс, значна спрыяе адлагоджэнню, калі ўжо не трэба думаць, чыі баг знаходзіцца ў API чы ў коде, які яго вызывае.

Працюючы, вяртайце адпаведныя коды статусу, а не 200 для всага: 201, калі POST стварае задачу, 404, калі id не існуе, 400, калі у тэле запыту не ёсць неабходнага поля. Самэ гэтыя маленькія выборы робяць API зручным для викорыстоўвання.

Дзе пачатківцы зазвычай застрэліваюцца

Людзі, які маюць труднасці з REST, рэдкасцю страждаюць ад недастатку спроможнасцяў. Яны часта зупіняюцца з прычын, якія можна ўсунуць:

• Адночасна вивучэнне концэпцый REST і фреймворка на кшталт Express, таму ніколі не ўсё ясна, якія правілы належаюць да HTTP, а якія — да бібліятэкі.
• Непрыменне тэставання маршрутаў безпосередна за дапамогою інструмента на кшталт Postman, што робіць багі фронтэнду і бэкэнду нерозразлівымі.
• Ігнораванне кодаў статусу і обробкі адзінакоў, пасля чаго вынашчваецца плутанне, калі кліент не можа розразліць успех і нявыпанне задачы.
• Прыступленне да аутентыкацыі раней, чым будуць створеныя базовыя маршруты для стварэння, чытання, апдэйта і выдалення дадзеных.
• Точна відтворэнне API з туторыялу заместо стварэння чагось маленькага з разнымі ресурсамі, што закрывае можлівасць з’ясаваць, чы былі концэпцыі зрозумелыя.

Это проблемы структуры, а не таланту. Якраз ўсуненне іх зазвычай і відрóżняе таго, хто справдзейшаю чынам добрэ вмее ствараць backend API, ад таго, хто можа запам’ятаваць тэрмінологію, але ўсё ще не можа спроектаваць канец-пункт з порожнія файла.

Адаптаванне падходу да вашага стартовага рівня

Тыя ж основы паслужаюць усім, але акцэнт змініцца залежна ад вашай ситуацыі.

• Студэнты отрымаюць корысть ад раннега вивучэння REST, таму што це зазвычай перша рэч, якая перетварае персональны проект з статычнай сторанкі на справжняе прыемлена.
• Людзі, які шукаюць работу, патрэбныя як практычныя навыки стварання та викорыстання API, так і здатнасць чыткаа ўсё це поясніць, адколі запытанні на тэму REST з’яўляюцца пад час спытанняў на багато вакансый.

Людзі, які меняюць працоўную дзеяльнасць, часта адчуваюць, што гэтыя ідеі ўсё ж прыемнейшыя, чым яны спачатку думалі; модель рестарана апоўнюецца ўседзённым дазнаўанням, а не тэхнічным фундаментам.

Разрабоўцы фронтэнду часта вучацца REST спецыяльна як мост да роботы з цэлым стаком, расширюючы свае навыкі без таго, каб абмовіцца ад таго, што вони вядомаюць.

Прывычкі, якія дапамагаюць закрепіць концэпцыі

Калькі прывычкі стаюць фактарам, які разлучае тых, хто справжньяго розумее REST, ад тых, хто проста ведае яго назву.

Створыце ўсё-такі што-небольшае і орыгінальнае, напрыклад, спіс задач або API для зьвярніка, а не проста чытайце дасведчэнні. Концэпцыі станавяцца болей стойкімі, калі вам даводзіцца налагадваць маршрут, які перастаў працаваць.

Навучыцеся діаграмаваць нештачы замест тагадвання. Адзінайце код статусу і паведамленне пра адказку, выявіце, чы гэта проблема на баку кліента чы сервера, і падтвердзіце це прымусовым запитам. У роботе такі інстынкт мае большое значэнне, чым запам’ятаваныя ваклікання, і самэ гэта адзінайце розлічвае таго, хто стварыў API, ад таго, хто толькі іх выкарыстоўваў. Калі вы праходзіце да аднаго ўжо вышэй, вярненне адказак у аднам і тым жа, задокументаваным формате спрабелівае дыягназу для всіх, хто выкарыстоўвае ваш API.

Атрымайце адзінайце зворотную свярону быстра. Магчымасць запытаць апытнага разработчыка, колегу чы учасника форума, чаму запыт вяртае некалькі неправильных дадзеных, часта ёсць розлік межы завершэнням першага проекту API і яго абандонаваннем. Дзялёны час пасыўнага перагляду відеа без такога циклу зворатной свяроны — гэта там, дзе багато учняў втрачаюць ініцыятыву.

Пашчэрпнутыя запытанні пачаткунава

Што такое REST API, ў адной фразе?

Это сэт прынцыпаў, якія дазволяюць аплікацыям камунікаваць через Інтэрнет за дапамой стандартных HTTP-запытоў і прыведжальных адпаведзей.

Чыяму разрабам фронтэнду трэба вучыцца REST?

Так. Работа над фронтэндам паўсюды включае сталое выкарыстоўванне REST API, таму практычна скроз апэкўваецца ўмеласцю яго викорыстоўвання. Гэта таксама адна з найпростыях дарог для тых, хто пазней жадае перайсці да разработкі на весь стак.

Чыяму REST складна выучыць?

Основныя ідэі стаюць зрозумелымі, калі іх чыста адказваць. Большая частка трудносцяў вынікла з аблыжанаяго тэрміналага ўжывання, а не з самых паняцэй.

Чыяму для стварэння бэкэнд-API трэба дыплом па інформатыцы?

Нята. Багато практыкуючых разрабоў, уключаючы тых, якія працуюць над весьм стакам, выучыліся за дапамой буткампаў, самастоятнаго вучэння або наставства, а не за дапамой формальнага дыплома.

Можна выучыць гэта працуючы на пэўную змяну?

Так. Канцэпцыі ўзмацненыя, і невялікі проект, створаны за калькі вечароў або выходных, дастатковы, ўбачлівае іх застосоўванне.

Заключэнне

REST не такі вельмі складны, як можа здавацца. Цэў стабільны спосаб для програмнага забезпечэння запрашваць і адправляць інфармацыю, створаны на адной з баз HTTP, якая вже выконвае функціі інтэрнету, і ён выкорыстоўваецца у большасці прыладоў, якія вы вжываеце ўпару.

• Пяць ідэй станавяць основу: рычаслі з URL, методы HTTP, запрошэння і адпаведзі, коды статусу і абсэнцыя стану.
• Выучыце канцэпцыі раней, чым фрэймворк, а потым выкарыстоўваеце Express, каб убачлівае ўпрактавіць іх.
• Апробавайце кожную маршрут аддзельна, прычым ніякі фронтэнд не павінен ад яго залежаць.
• Спрыяйце кодам статусу і карэспандаванню з адказамі на праблемы як частцы дизайну, а не як чамусь, што рашаецца пазней.

Створыце ўсёга невялікі і орыгінальны прылад, а таксама научыце діаганаваць нештачы замест тагадзявання.