Како да дизајнирате добро REST API?

Ако не многу одамна API сервисите служеа единствено за интеграција со надворешни апликации, денес ситуацијата е сосема поинаква. Со сѐ поголемиот капацитет на frontend рамките и библиотеките, начинот на кој се справуваме со позадинскиот дел на апликациите е значително променет. Па, доколку сте backend програмери, веројатноста е голема дека во даден момент ќе се соочите со REST.

REST доаѓа од Representational state transfer и е архитектонски стил за дизајнирање на веб сервиси. Еве што треба да имате на ум при дизајнирање на REST сервиси.

Одржувајте униформиран интерфејс

При дизајнирање на REST API, ова е првото нешто на кое треба да се фокусирате. Униформираниот интерфејс е основното својство кое го разликува REST од другите архитектонски стилови.

Основните карактеристики на униформниот интерфејс се постоење на ресурс за секој релевантен сегмент од вашето API, идентификација на тие ресурси со URI и постојано враќање на конзистентна репрезентација на ресурсот. Идентификаторот на ресурсот секогаш треба да оди во URL, наспроти како query string параметар. Query string параметрите се користат исклучиво за филтрирање.

Одржувајте јасна URL хиерархија

Искористете ја хиерархалната природа на URL за да ја зголемите јасноста на вашето API. На пример:

/users/223/addresses

Ова URL нема потреба од дополнително објаснување. По самото читање на патеката точно знаеме за кој ресурс се работи (адресите за корисникот со ID 223).

Одржувајте конзистентност на имињата на ресурсите и нивните идентификатори (URIs)

    1. Секогаш користете именки како имиња на ресурсите за да ја подобрите јасноста.
      За разлика од SOAP сервисите, каде имаме многу дескриптивни URLs, REST сервисите користат комбинација на ресурс и HTTP глагол за да ја опишат акцијата. Па така, наместо:
      /user_list
      за индикација дека барањето враќа листа на корисници, кај REST се користи:
      GET /users
    2. За задржување на конзистентноста на уникатниот идентификатор на ресурсот (URI) низ сите HTTP методи, постојано користете множина во URL сегментите. Ова значи дека за земање на листата на корисници, би требало да пристапите со:
      /users
      додека за да ги земете деталите за специфичен корисник:
      /users/223
      каде 223 е уникатното ID за дадениот корисник.
    3. Користете само мали букви во URL, делејќи ги зборовите со долна црта (‘_’) или тире (‘-’).

Одржувајте што е можно пократко URL

Иако целта е да се обезбеди што е можно појасна структура преку URL на ресурсот, сепак треба да внимавате да не завршите со предолгo URL. Придржувајќи се до насоките погоре, би требало да имате кратки URL-a што се доволно јасни и конзистентни.

Користете HTTP глаголи

По дефинирањето на ресурсите со помош на именки, следен чекор е додавање на значење на барањата со помош на HTTP глаголи. Четирите најчесто користени се:

GET — за барање на колекција од ресурси или детали за специфичен ресурс согласно пратен идентификатор.

PUT — ажурирање на даден ресурс согласно испратениот идентификатор или креирање на нов ресурс каде идентификаторот е однапред дефиниран.

DELETE — бришење на ресурс преку праќање на неговиот уникатен идентификатор.

POST — креирање на нов ресурс. Може да се користи и како генерален глагол кога дадена акција не припаѓа во ниедна конкретна категорија.

Во однос на нашиот User ресурс од погоре, ова се можните HTTP барања:

GET /users

GET /users/223

PUT /users/223

POST /users

DELETE /users/223

Враќајте јасни одговори

Без разлика дали станува збор за успешно барање или грешка, клиентот кој зависи од вашето API ќе има потреба од јасни и конзистентни одговори кои недвосмислено ќе му покажат како да продолжи понатаму.

Користете ги HTTP статусните кодови за да го прикажете статусот на барањето секогаш кога вашето API враќа некаков одговор. На пр., вратете 404 ако записот не е пронајден или 401 ако корисникот не е авторизиран да ја изврши саканата операција. Кога барањето е успешно извршено, секогаш е во ред да вратите 200. Но, уште подобро е кога кодот за успех е поконкретен, на пример 201 ако е креиран нов запис или 204 ако операцијата е успешна, но API-то не враќа ништо (најчесто случај со методите PUT и DELETE).

Целта е да бидете сигурни дека клиентот може да разбере точно кој е статусот на операцијата и како треба да продолжи понатаму во случај на грешка. Тука можете да ја разгледате целата документација на HTTP статусните кодови со повеќе детали за специфични сценарија.

Дополнително, кога клиентот бара колекција од ресурси, секогаш обрнете внимание на тоа одговорот да враќа детали за ограничувањата и пагинацијата на вратените ресурси.

{

   "metadata": {

       "resultset": {

           "count": 1225,

           "offset": 100,

           "limit": 25

       }

   },

   "results": []

}

Не ја чувајте состојбата на апликацијата

Состојбата на апликацијата е податок кој на серверот му е потребен за да заврши дадено барање. За разлика од состојбата на ресурсот која е константна без разлика кој ја бара, состојбата на апликацијата зависи од клиентот и може да варира помеѓу барања. Најдобар пример е автентикација на корисникот – податоците зависат од клиентот, а според нив, серверот треба да провери дали клиентот е авторизиран да ја изврши дадената операција пред да врати одговор.

REST сервисите се секогаш без-состојбени, што значи дека податоците треба да се праќаат со секое барање. Така, автентикацијата се извршува комплетно на клиентската страна, а серверот ги добива податоците за состојбата со секое барање. Ова можеби има некое незначително влијае врз перформансите, но ја подобрува видливоста, скалабилноста и сигурноста на апликацијата.

Како се случува тоа?

Бидејќи податоците за состојбата се праќаат со секое барање (како дел од URL, query string параметрите, телото или хедерот на барањето), со единствен поглед на HTTP барањето, може да ги добиеме сите податоци за него без дополнително истражување и мониторирање. Дополнително, со пренесувањето на податоците со секое барање, се обезбедува полесно опоравување од парцијални падови на системот. Тоа значи подобра видливост и сигурност.

Со комплетно манипулирање со состојбата само на клиентската страна, серверот нема потреба да го менаџира искористувањето на ресурсите помеѓу барањата. Едноставно, ги добива сите потребни податоци и враќа соодветен одговор. Тоа значително ја поедноставува имплементацијата и овозможува брзо ослободување на ресурсите, што резултира со поскалабилен сервер.

Популарна варијанта за одржување на без-состојбеноста и безбедноста при зачувување и трансфер на податоците помеѓу клиентот и серверот е JSON Web Token (JWT). JWT е отворен стандард (RFC 7519) кој обезбедува интегриран начин за безбедно пренесување на информации помеѓу двете страни во вид на JSON објект.

Дефинирајте верзии

Со оглед на брзината со која технологијата се развива, голема е веројатноста дека процесите и ресурсите на вашето API ќе се променат со тек на време.

Креирање на верзии за вашето API уште од самиот почеток ќе придонесе кон неговата конзистентност и ќе го направи полесен процесот на upgrade и за вас, како и за девелоперите што ќе го користат. Најдобриот пристап за креирање верзии е додавање на API верзијата на URL-то. Во нашиот пример, целосното URL за враќање на колекција од корисници ќе биде:

yourdomain.com/api/v1/users

Документирајте

Колку и да не ни е омилено, документирањето е клучно за секој кој ќе го користи вашето API. Вашата документација треба соодветно да ги опишува класите и методите на вашето API и да вклучи пример код што покажува како истите се користат.

Постојат алатки кои може да ги користите за автоматско генерирање на веб документација од коментарите во изворниот код. Една од нив е apiDoc која поддржува повеќе програмски јазици и е релативно лесна за употреба.