REST API: ano ito, mga pamamaraan ng HTTP at prinsipyo ng paggamit sa mga mobile application

Ano ang REST API?

REST API (Representational State Transfer API) — ay isang arkitekturang estilo na iminungkahi ni Roy Fielding sa kanyang doctoral dissertation noong 2000. Tinutukoy nito ang isang set ng mga limitasyon at prinsipyo para sa pagdisenyo ng mga network protocol. Ang API na sumusunod sa mga limitasyong ito ay tinatawag na RESTful. Ang REST ay hindi isang protocol o standard — ito ay isang arkitekturang approach na gumagamit ng mga umiiral na protocol (pangunahin ang HTTP) para sa pagpapalitan ng data sa pagitan ng client at server.

Ang pangunahing ideya ng REST ay resource-oriented architecture. Sa halip na tumawag ng mga pamamaraan sa server (tulad ng sa SOAP o RPC), ang client ay nag-ooperate sa mga resource: kinukuha ang kanilang listahan, gumagawa ng bago, nag-a-update, o nagtatanggal. Ang bawat resource ay isang entity ng domain: user, order, produkto, artikulo. Ang resource ay may estado na ipinapadala sa client sa isang standardized na format, karaniwang JSON. Hindi iniimbak ng server ang estado ng client sa pagitan ng mga request — ito ang prinsipyong stateless, isang pangunahing pangangailangan ng REST.

Mga pangunahing katangian ng REST API:

• Stateless — bawat request mula sa client ay naglalaman ng lahat ng impormasyong kailangan para sa pagproseso nito
• Cacheable — ang mga tugon ng server ay dapat na malinaw na minarkahan bilang cacheable o non-cacheable
• Layered system — ang arkitektura ay maaaring magsama ng mga intermediate server, load balancer, proxy
• Uniform interface — pare-parehong interface ng interaksyon sa pamamagitan ng HTTP methods, URL, at status codes

Mga prinsipyo ng REST architecture

REST ay batay sa anim na arkitekturang limitasyon na binuo ni Fielding. Ang pagsunod sa mga limitasyong ito ay ginagarantiyahan ang scalability, performance, at kadalian ng integrasyon. Bawat prinsipyo ay lumulutas ng isang partikular na problema ng mga distributed system — mula sa pangangailangan ng caching hanggang sa mga kinakailangan sa seguridad. Suriin natin ang bawat prinsipyo nang detalyado.

Ang prinsipyong Uniform Interface ay karagdagang may kasamang apat na sub-limitasyon: pagkakakilanlan ng mga resource sa pamamagitan ng URI, pagmamanipula ng mga resource sa pamamagitan ng mga representasyon, self-descriptive na mga mensahe, at HATEOAS (hypermedia bilang engine ng estado ng application). Ang huling sub-limitasyon ay madalas na binabalewala sa praktika — karamihan sa mga modernong REST API ay hindi ganap na nag-iimplementa ng HATEOAS, na humahantong sa mga diskusyon kung ang naturang API ay ‘tunay’ na RESTful.

Ang prinsipyong Stateless — isa sa pinakamahalaga para sa scaling. Ang kawalan ng mga sesyon sa server ay nangangahulugan na ang anumang instance ng server ay maaaring magproseso ng anumang request. Pinapasimple nito ang horizontal scaling: sapat na ang magdagdag ng mga bagong server sa likod ng load balancer. Para sa mga mobile application, ang stateless ay nangangahulugan din na ang request ay maaaring ipadala sa anumang CDN server, na kritikal para sa pandaigdigang accessibility.

Mga pamamaraan ng HTTP sa REST

Bawat HTTP method sa REST API ay tumutugma sa isang partikular na operasyon sa resource: GET para sa pagbasa, POST para sa paggawa, PUT para sa buong pag-update, PATCH para sa bahagyang pag-update, DELETE para sa pagtanggal. Ang idempotency ng mga pamamaraan ay isang pangunahing katangian: GET, PUT, DELETE ay idempotent (paulit-ulit na pagpapatupad ay nagbibigay ng parehong resulta), ang POST at PATCH ay hindi. Ito ay mahalaga para sa paghawak ng mga error sa network kapag hindi alam ng client kung ang request ay nakarating sa server.

• GET — pagkuha ng resource o listahan ng mga resource. Idempotent, hindi binabago ang estado ng server
• POST — paggawa ng bagong resource. Hindi idempotent, bawat tawag ay gumagawa ng bagong resource
• PUT — buong pagpapalit ng resource. Idempotent, paulit-ulit na tawag ay hindi nagbabago ng estado pagkatapos ng una
• PATCH — bahagyang pag-update ng resource. Bahagyang idempotent (depende sa implementasyon)
• DELETE — pagtanggal ng resource. Idempotent, paulit-ulit na pagtanggal ay nagbabalik ng 404, hindi error

Ang mga HTTP status code ay isang mahalagang bahagi ng REST API. Bawat code ay may tiyak na kahulugan: 200 OK para sa matagumpay na GET, 201 Created para sa POST, 204 No Content para sa DELETE na walang body ng tugon, 400 Bad Request para sa hindi valid na data, 401 Unauthorized kapag walang authentication, 404 Not Found kapag walang resource. Ang tamang paggamit ng status codes ay ginagawang self-documenting ang API at pinapasimple ang debugging.

Mga format ng data: JSON at iba pa

JSON (JavaScript Object Notation) — pangunahing format ng pagpapadala ng data sa REST API. Ang kasikatan nito ay ipinaliwanag ng pagiging simple, pagiging nababasa ng tao, at native na suporta sa JavaScript. Ang JSON ay ipinapadala na may header na Content-Type: application/json. Kasama sa mga alternatibo ang XML (malaki, lumulumang), YAML (maginhawa para sa configuration, bihira para sa API), at Protocol Buffers (binary, epektibo para sa mga system na may mataas na load).

Ang estruktura ng JSON object sa REST API ay karaniwang may kasamang mga field na id, type, at mga attribute ng resource. Para sa mga koleksyon, ginagamit ang JSON array na may metadata ng pagination. Ang mga modernong REST API ay sumusunod sa JSON:API specification (jsonapi.org) o JSON Schema para sa validation ng mga tugon. Ang paggamit ng pare-parehong format ng data ay pinapasimple ang pag-develop ng client libraries at pagbuo ng dokumentasyon.

Halimbawa ng JSON na tugon para sa listahan ng mga user:

{
    "data": [
        {
            "id": 1,
            "name": "Anna Petrova",
            "email": "anna@example.com"
        }
    ],
    "meta": {
        "total": 42,
        "page": 1,
        "per_page": 10
    }
}

Ang pagpili ng format ng pagpapadala ng data ay nakakaapekto sa performance ng mobile application. Ang JSON ay na-compress sa pamamagitan ng GZIP ng 70–80%, na ginagawa itong katanggap-tanggap para sa karamihan ng mga sitwasyon. Para sa real-time na application na may malaking volume ng data (streaming, laro), inirerekomenda na lumipat sa binary protocols o gumamit ng WebSocket kasama ng Protocol Buffers.

Mga halimbawa ng REST API requests

Tingnan natin ang mga praktikal na halimbawa ng pagtatrabaho sa REST API sa panig ng mobile application. Bilang halimbawa, kumuha tayo ng API para sa pagtatrabaho sa mga order sa isang online na tindahan. Para sa bawat HTTP method, ipinapakita ang request at inaasahang tugon ng server. Ipinapakita ng mga halimbawa ang tipikal na estruktura ng RESTful API na ginagamit sa mobile development.

GET — pagkuha ng listahan ng mga order

Request para makuha ang lahat ng order ng user na may pagination. Ang tugon ay naglalaman ng array ng mga order object at meta-impormasyon para sa page navigation. Ang mga parameter na page at per_page ay ipinapadala sa pamamagitan ng query string.

// Retrofit interface para sa REST API
interface OrderApi {
    @GET("api/v1/orders")
    suspend fun getOrders(
        @Query("page") page: Int = 1,
        @Query("per_page") perPage: Int = 20
    ): Response<OrderListResponse>
}

POST — paggawa ng bagong order

Paggawa ng bagong order sa pamamagitan ng POST request. Ang server ay nagbabalik ng status 201 Created at ang nilikhang object sa body ng tugon. Mahalaga: ang paggawa ay ginagawa sa koleksyon /api/v1/orders, hindi sa isang partikular na resource — ito ay isang karaniwang RESTful pattern.

@POST("api/v1/orders")
suspend fun createOrder(
    @Body order: CreateOrderRequest
): Response<OrderResponse>

// Halimbawa ng body ng request
data class CreateOrderRequest(
    val productId: String,
    val quantity: Int,
    val addressId: String
)

DELETE — pagtanggal ng order

Ang pagtanggal ng resource ay ginagawa sa pamamagitan ng DELETE method sa partikular na URL ng order. Ang matagumpay na pagtanggal ay nagbabalik ng 204 No Content. Ang idempotency ng DELETE ay nangangahulugan na ang paulit-ulit na request sa parehong URL ay magbabalik ng 404 Not Found, na wastong pinangangasiwaan sa panig ng client.

@DELETE("api/v1/orders/{id}")
suspend fun deleteOrder(
    @Path("id") orderId: String
): Response<Unit>

// Paggamit sa ViewModel
fun removeOrder(orderId: String) {
    viewModelScope.launch {
        val response = api.deleteOrder(orderId)
        if (response.isSuccessful) {
            showSuccess()
        }
    }
}

Ang mga halimbawang ito ay nagpapakita ng tipikal na implementasyon ng REST API sa panig ng Android gamit ang Retrofit at Kotlin Coroutines. Para sa iOS application, ang katulad na papel ay ginagampanan ng URLSession o Alamofire library kasama ng Codable protocols. Ang estruktura ng REST API ay nananatiling pareho anuman ang platform — tanging ang paraan ng pag-execute ng mga request ang nagbabago.

Disenyo ng RESTful API: praktikal na rekomendasyon

Ang pagdisenyo ng de-kalidad na RESTful API ay nangangailangan ng pagsunod sa mga convention na ginagawang intuitive ang API para sa mga developer. Ang mga resource ay dapat pangalanan gamit ang plural nouns (/users, /orders, /products), ang HTTP methods ay dapat sumalamin sa mga operasyon, at ang mga URL ay dapat magpakita ng hierarchical na estruktura. Ang mga error ay dapat magbalik ng standardized JSON na may code at mensahe, hindi lang HTTP status. Ang pagsunod sa mga convention na ito ay nagpapababa ng hadlang para sa mga bagong developer at pinapasimple ang integrasyon.

• Pagpapangalan ng resource — plural, kebab-case: /api/v1/user-orders, hindi /api/v1/getUserOrders
• Pagsala at pag-uuri — sa pamamagitan ng query parameters: ?status=active&sort=created_at:desc
• Pagination — cursor-based para sa malalaking set, page-based para sa maliliit
• Pag-version — sa pamamagitan ng URL (/api/v2/) o header na Accept-Version
• Mga error — pare-parehong format: { "error": { "code": "VALIDATION_ERROR", "message": "..." } }
• Rate limiting — mga header na X-RateLimit-Remaining at Retry-After

Isa sa mga karaniwang pagkakamali sa pagdisenyo ng REST API ay ang labis na nesting ng mga resource. Sa halip na /users/1/orders/5/items/3, mas mainam na gumamit ng flat na estruktura na may query parameters: /items?order_id=5&user_id=1. Pinapasimple nito ang caching, hindi nangangailangan ng suporta sa mahabang path sa server, at mas madaling idokumento. Ang flat na arkitektura ay mas compatible din sa graph-based na mga request kapag lumipat sa GraphQL sa hinaharap.

Ang seguridad ng REST API ay naisasagawa sa pamamagitan ng authentication (JWT, OAuth 2.0) at authorization sa antas ng resource. Bawat request ay dapat suriin kung ang user ay may access sa hinihinging resource. Ang HTTPS ay mandatory — walang encryption, ang mga token at data ay ipinapadala sa plain text. Para sa mga mobile application, inirerekomenda ang paggamit ng OAuth 2.0 na may PKCE (Proof Key for Code Exchange) para sa ligtas na pagkuha ng mga token.

Pag-version at caching

Ang pag-version ng REST API ay kinakailangan para sa backward compatibility sa mga pagbabago. Ang pinakakaraniwang approach: version sa URL (/api/v1/orders), version sa header (Accept: application/vnd.myapi.v1+json), at version sa query parameter (?api_version=1). Ang URL versioning ay ang pinakasikat na paraan dahil malinaw itong nakikita sa logs at dokumentasyon. Gayunpaman, nilalabag nito ang prinsipyo ng REST tungkol sa natatanging URL ng resource.

Ang caching sa REST API ay naisasagawa sa pamamagitan ng HTTP headers na Cache-Control, ETag at Last-Modified. Ang GET requests na minarkahan bilang cacheable ay maaaring serbisyuhan mula sa cache ng browser o proxy nang hindi kumokonekta sa server. Para sa mga mobile application, ang caching ay lalong mahalaga — binabawasan nito ang paggamit ng data at pinapabilis ang pagpapakita ng dating na-load na data sa mahinang koneksyon. Ang ETag ay isang hash ng nilalaman ng tugon: ipinapadala ito ng client sa If-None-Match, at ang server ay nagbabalik ng 304 Not Modified kung hindi nagbago ang data.

Ang mga modernong alternatibo sa REST API ay kinabibilangan ng GraphQL (flexible na pagpili ng data ng client) at gRPC (binary protocol sa HTTP/2 para sa microservices). Gayunpaman, ang REST ay nananatiling pangunahing standard para sa pampublikong API dahil sa pagiging simple, universality, at malawak na suporta sa mga tool. Ang pagpili sa pagitan ng REST at mga alternatibo ay depende sa mga tiyak na pangangailangan ng proyekto: pagiging kumplikado ng mga request, volume ng data, mga kinakailangan para sa real-time na pag-update.